Enhancement: Domain Registration — Multi-Registrar Abstraction Layer

[brian-toresdahl-datum]

Summary

Datum will support users registering and managing domains via one or more domain resellers (registrar/reseller partners). To keep Datum’s UX consistent and maintainable while preserving a “neutral control plane” posture, Datum should introduce a Multi-Registrar Abstraction Layer: a provider-pluggable approach that normalizes domain lifecycle states, supported actions, and user-facing error messaging across resellers.

Datum is also prioritizing agentic (AI agentic) usability across product surfaces. This enhancement must ensure domain workflows are safe, automatable, and observable for agents operating via Datum APIs and tools.

This enhancement is intended to:

• Enable Datum to launch with a single default reseller while being architected to add others later
• Reduce vendor lock-in and mitigate operational risk
• Avoid user confusion by clearly surfacing which reseller/registrar holds a domain and what actions are available
• Provide agent-friendly workflows that are deterministic, retry-safe, and auditable

Goals

• Provide a consistent domain registration and management experience regardless of reseller
• Support a “preferred provider” default, with the ability to add alternative providers over time
• Clearly represent provider ownership, domain lifecycle state, and supported actions in the UI and API
• Improve operational supportability through normalized states and user-facing errors
• Enable agentic operation: long-running workflows, retries, and troubleshooting without human guesswork

Non-Goals

• “Failover” or active-active redundancy for a single domain across multiple resellers (a domain is registered at one provider at a time)
• Replacing the need for resellers by implementing full registrar/registry operations inside Datum
• Achieving perfect feature parity across all resellers in the first iteration

Motivation / Context

Resellers differ meaningfully in TLD coverage, transfer edge cases, renewal behavior, privacy options, async behavior, rate limits, pricing models, and support processes. Datum should avoid embedding reseller-specific assumptions into core product UX and APIs. A normalized abstraction reduces long-term complexity, enables optional provider choice, and aligns with Datum’s goal of being a neutral open platform.

Agentic-first usability requires that these workflows are not only human-friendly, but also machine-operable: deterministic state, structured constraints, safe retries, and clear next actions.

User Experience Principles

• Every domain clearly shows:
  • Registrar provider (who holds the domain)
  • Current lifecycle state (e.g., pending registration, active, pending transfer)
  • Available actions (based on provider + TLD + state)
• Provider selection is straightforward:
  • Default to the preferred provider
  • Only expose alternate provider choice when needed (e.g., coverage, compliance, customer requirement)
• Agentic workflows:
  • Agents can discover supported actions and constraints via structured signals
  • Agents can safely retry operations without duplicate purchases
  • Long-running actions are observable with clear statuses and next steps

Agentic Surfaces (Portal / API / CLI / MCP)

Domain registration and lifecycle workflows must be usable consistently across:

• Portal UX
• Datum declarative API (Kubernetes-style resources)
• datumctl (CLI + automation)
• MCP for AI tools (datum-mcp, and optionally datumctl mcp)

Agentic usability requires:

• machine-readable lifecycle states and “requires user action” states
• stable operation identifiers for async workflows
• safe retries (idempotent intent), and an auditable trail of actions

---

User Stories

Datum user (Portal)

1. Register a domain (default provider)

   • As a Datum user, I can search for and register a domain, and Datum will select the default provider automatically.
   • Acceptance: The domain appears in my domains list with a clear status (e.g., pending → active) and indicates which provider holds it.

2. Register a domain (provider choice when applicable)

   • As a Datum user, I can select an alternate provider when necessary (e.g., a specific TLD is only supported by that provider).
   • Acceptance: The UI only presents provider choice when it materially matters, and the selected provider is visible on the domain record.

3. Transfer a domain into Datum

   • As a Datum user, I can initiate a transfer into Datum and understand what is required (auth code, unlock, timing) without reseller-specific jargon.
   • Acceptance: Transfer progress is visible with clear next steps and a normalized status that updates until completion or failure.

4. Renew a domain / enable auto-renew

   • As a Datum user, I can renew a domain and enable/disable auto-renew in a consistent way across providers.
   • Acceptance: The next renewal date and renewal state are clearly visible; unsupported actions are disabled with an explanation.

5. Manage nameservers

   • As a Datum user, I can update nameservers for my domain in a consistent way across providers.
   • Acceptance: Changes reflect an appropriate status (e.g., “updating”) until confirmed, and errors are actionable.

6. Manage contacts and privacy (when supported)

   • As a Datum user, I can update domain contacts and toggle WHOIS/privacy features when available for that domain/provider.
   • Acceptance: If an action is not supported for a given provider/TLD, I see why and what alternatives exist.

7. Understand errors and support boundaries

   • As a Datum user, when an action fails, I receive a clear, actionable message (what happened, what to do next).
   • Acceptance: Messages avoid provider-specific codes and provide next steps (retry, update input, contact support).

Datum user (API / automation)

8. Automate domain lifecycle via Datum API

   • As a Datum user, I can automate domain registration/transfer/renewal via the Datum API using declarative resources, and observe progress via normalized status fields.
   • Acceptance: A single resource-driven workflow can be executed end-to-end via API, including visibility into long-running operations and “requires user action” states.

9. Safe retries for automation

   • As a Datum user, I can retry domain operations safely in automation without risking duplicate purchases or duplicate transfers.
   • Acceptance: The system provides a way for automation to express idempotent intent, and clearly reports when an operation is already in-flight or already completed.

Datum user (CLI / automation: datumctl)

10. Register and manage domains via datumctl

• As a Datum user, I can search/register/renew/transfer/manage nameservers for domains using datumctl, so I can automate workflows in scripts and CI.
• Acceptance: datumctl exposes the same normalized lifecycle states and actionable errors as the Portal/API.

11. Track async domain operations via datumctl

• As a Datum user, I can list and inspect in-flight domain operations (registration, transfer, renewal) via datumctl, so I can monitor progress and handle retries.
• Acceptance: Each operation has a stable ID, a normalized status, and (when applicable) a clear “requires user action” prompt that can be surfaced in CLI output.

Datum user (agent-assisted via MCP)

12. Agent-assisted domain registration via MCP

• As a Datum user, I can ask an AI agent connected via MCP to register a domain and complete the workflow without manual back-and-forth unless legally required.
• Acceptance: The agent can initiate the workflow, monitor operation status, and report a concise audit of actions taken.

13. Agent-assisted transfer with guided requirements via MCP

• As a Datum user, I can ask an AI agent connected via MCP to transfer a domain into Datum, and the agent can determine prerequisites and prompt me only for missing inputs.
• Acceptance: The agent can detect “requires user action” states and request exactly what’s missing in one concise prompt.

Datum staff

14. Add a registrar provider without redesigning product UX

• As Datum staff, I can add a new reseller integration without changing core domain UX or rewriting core flows.
• Acceptance: Provider-specific behavior maps cleanly to Datum’s normalized states and actions.

15. Configure preferred provider and provider availability

• As Datum staff, I can configure a preferred/default provider for new registrations and disable/limit a provider if degraded.
• Acceptance: New registrations follow configuration; existing domains remain managed at their current provider.

16. Operate with provider ownership clarity

• As Datum staff, I can quickly determine which provider holds a domain and what the last known lifecycle state is.
• Acceptance: Provider ownership and state are visible in staff tooling and exported logs.

17. Triage failures efficiently

• As Datum staff, I can distinguish between Datum issues vs provider issues vs registry issues using normalized statuses and error categories.
• Acceptance: Support workflows are consistent across providers and reduce time-to-diagnosis.

18. Support provider differences safely

• As Datum staff, I can handle cases where actions vary by provider or TLD without bespoke one-off handling in the UI.
• Acceptance: Provider/TLD constraints are represented as product behavior (available/disabled actions) rather than hidden quirks.

19. Audit and accountability

• As Datum staff, I can audit key domain lifecycle operations (register/transfer/renew) with timestamps and provider attribution.
• Acceptance: The system reliably records “what happened, when, and via which provider” for support and billing reconciliation.

Datum staff (agentic operations)

20. Agent-safe provider routing

• As Datum staff, I can configure routing policies that agents can follow deterministically (preferred provider, allowed/disallowed providers, constraints).
• Acceptance: Provider selection decisions are explainable and recorded so agent behavior is auditable.

21. Agentic triage and escalation

• As Datum staff, I can use an agent to triage domain lifecycle issues using normalized statuses/errors and provider ownership, and the agent can suggest next actions or escalation paths.
• Acceptance: The agent can distinguish “user action required” vs “provider incident” vs “Datum bug” based on structured signals, and produce an auditable trail of actions taken.

[brian-toresdahl-datum]

related issue: https://github.com/datum-cloud/engineering/issues/149#issuecomment-3802637520

[brian-toresdahl-datum]

adding support for agentic workflows

[brian-toresdahl-datum]

some registrar / resellers that can plug into Datum: https://github.com/orgs/datum-cloud/discussions/166

[brian-toresdahl-datum]

dependency: payment