feat: add name.com API tool with username/token auth

[avoidwork]

Summary

Add a name.com API tool that wraps the full name.com Core API (72 operations across 17 tag groups) as a single unified tool with an action parameter, similar to the existing process and email tools. Authentication uses a username/token combo via environment variables.

Motivation

Users need to manage domains, DNS records, transfers, and related services through name.com's API. Currently there is no tool for this in the harness. A single unified tool with an action parameter keeps the tool surface clean while providing full API coverage.

Proposed Solution

Create a single namecom tool (e.g., src/tools/namecom/index.js) that accepts an action field and additional keys for task-specific parameters. The tool maps actions to the underlying API endpoints.

Authentication:

• NAMECOM_USERNAME — environment variable for the API username
• NAMECOM_TOKEN — environment variable for the API token
• Basic auth (username:token) is used for all requests
• Base URL: https://api.name.com/v1 (production) or https://api.dev.name.com/v1 (testing)

Action design:
Actions map to the 17 API tag groups, with CRUD-style sub-actions where applicable:

Tag Group	Actions
Domains (19 ops)	listDomains, createDomain, getDomain, updateDomain, enableAutorenew, disableAutorenew, enableWhoisPrivacy, disableWhoisPrivacy, lockDomain, unlockDomain, renewDomain, setContacts, setNameservers, getAuthCode, getPricing, checkAvailability, searchDomains, zoneCheck, purchasePrivacy
DNS (5 ops)	listRecords, createRecord, getRecord, updateRecord, deleteRecord
URL Forwardings (9 ops)	listUrlForwardings, createUrlForwarding, getUrlForwarding, updateUrlForwarding, deleteUrlForwarding
Email Forwardings (5 ops)	listEmailForwardings, createEmailForwarding, getEmailForwarding, updateEmailForwarding, deleteEmailForwarding
Vanity Nameservers (5 ops)	listVanityNameservers, createVanityNameserver, getVanityNameserver, updateVanityNameserver, deleteVanityNameserver
DNSSECs (4 ops)	listDnssecs, createDnssec, getDnssec, deleteDnssec
Transfers (7 ops)	listTransfers, createTransfer, getTransfer, cancelTransfer, cancelExternalTransferOut, createInternalTransferIn, getTransferEligibility
Webhook Notifications (4 ops)	listNotifications, subscribeNotification, getNotification, modifyNotification, deleteNotification
Domain Info (3 ops)	getTldRequirements, checkDomainClaims, getTldRequirementsV2
Contact Verification (3 ops)	listUnverifiedContacts, verifyContact, resendContactVerification
Orders (2 ops)	listOrders, getOrder
Account Info (1 op)	getAccountBalance
Accounts (1 op)	createAccount
Refunds (1 op)	processRefund
TLD Pricing (1 op)	getTldPricing
Premium Domains (1 op)	getPremiumDomainsList
Hello (1 op)	hello

Example usage:

{
  "action": "listDomains",
  "perPage": 250,
  "page": 1
}

{
  "action": "createRecord",
  "domainName": "example.com",
  "type": "A",
  "name": "www",
  "value": "192.168.1.1",
  "ttl": 3600
}

Alternatives Considered

• Separate tools per tag group — Would create 17+ tools, bloating the tool surface. A single tool with action is cleaner and matches the existing email and process patterns.
• Auto-generate from OpenAPI spec — Could use a codegen approach, but the API has 72 operations with varying parameters. A hand-crafted tool with explicit Zod schemas provides better type safety and error handling.

Dependencies

• No external npm packages required — uses fetch (native Node.js) for HTTP requests
• Zod for input validation (already a project dependency)

Testing Strategy

• Unit tests: Verify Zod schema validation for all action types, mock API responses for each tag group
• Integration test: Mock HTTP fetch to verify request construction (URL, headers, body) for representative actions across all 17 tag groups
• Edge cases: Rate limit handling (429 responses), authentication failures (401/403), invalid domain names, missing required parameters

Security Considerations

• Credential storage: All API credentials stored in process.env only (NAMECOM_USERNAME, NAMECOM_TOKEN) — never in config files
• Input validation: Validate all user input against Zod schemas before making API requests
• OWASP: URL allowlist validation for outbound requests (only api.name.com and api.dev.name.com), rate limit handling, no sensitive data in logs

Environment

• OS: Linux 7.0.2-7-pve
• Node.js: v25.8.1
• madz version: 1.49.2
• LLM provider: Unknown — user to confirm

OpenSpec Note

This project uses OpenSpec for feature development. If this request is approved, I will:

1. Run /opsx:propose to generate a full proposal with specs and tasks
2. Iterate on the design before any code is written
3. Follow the task-driven implementation workflow

Additional Context

The name.com API spec is available at tmp/namecom.api.yaml (OpenAPI 3.1.0, 18088 lines). Authentication is Basic Auth with username:token. Rate limited to 20 requests/second. The API covers domain registration, DNS management, transfers, email forwarding, URL forwarding, vanity nameservers, DNSSEC, webhook notifications, orders, refunds, TLD pricing, premium domains, and contact verification.

Audit Findings (for Issue #853)

• src/tools/index.js — Main tool registry. Needs: import statement, TOOL_PERMISSIONS entry, TOOL_CLASSIFICATIONS entry, TOOLS object entry, and buildToolConfig switch case. Pattern: email tool at line 205 is the closest reference for action-based tools.
• src/tools/email/tools.js — Best reference for the action-based tool pattern. Uses Zod schema with .enum() for action, all other params as optional fields. Tool registration via tool(async (input) => emailImpl(input, { config }), { name, description, schema }).
• src/tools/calendar/index.js — Another action-based tool reference. Shows how to handle provider config validation and credential checking.
• No existing name.com integration — This is a greenfield feature. No existing API client, no existing config structure for username/token auth.
• Auth pattern — Other tools (email, calendar) use provider configs from config.js. For name.com, the username/token combo should follow the same pattern: config.providers.namecom with username and token fields, resolved from NAMECOM_USERNAME and NAMECOM_TOKEN env vars.
• Rate limiting — The API is rate-limited to 20 requests/second. Consider implementing a simple request queue or delay mechanism for bulk operations.
• 72 operations across 17 tag groups — The Zod schema will be large. Consider grouping related actions into sub-objects or using a flexible params field for action-specific parameters.

Fix Steps

1. Create the tool file — Add src/tools/namecom/index.js with a Zod schema and impl function. Use the email tool (src/tools/email/tools.js) as the primary reference for the action-based pattern.
2. Define the Zod schema — Create a schema with action as an enum of all 40+ action names, plus optional fields for domainName, perPage, page, and other common parameters. Consider using a params record for action-specific fields.
3. Implement the action router — In namecomImpl()\), use a switch statement on actionto route to handler functions. Each handler makes an HTTP request to the appropriate endpoint usingfetch()` with Basic auth.
4. Register the tool — Add the tool to src/tools/index.js: import, TOOL_PERMISSIONS entry (["network:outbound"]), TOOL_CLASSIFICATIONS entry, TOOLS object entry, and buildToolConfig switch case.
5. Write unit tests — Add tests/unit/tools/namecom.test.js covering schema validation, action routing, and error handling for each tag group.
6. Verify — Run npm run test, npm run lint, and npm run coverage to confirm everything passes.

[avoidwork]

Fixed in #854.