secure_registrar

README

Secure Registrar Engine

The secure_registrar package provides a robust governance and administrative layer for domain management within the 0TrustCloud ecosystem. It implements a zero-trust architecture where ownership of namespaces (TLDs, root domains, and subdomains) is cryptographically verified and enforced via a centralized registry engine.

Core Features

• Hierarchical Ownership: Enforces strict parent-child relationships. Subdomain registration is only permitted if the caller proves ownership of the parent domain.
• Cryptographic Identity: Every state-changing operation (domain registration, DNS updates, UI configuration) requires an X-Identity-Public-Key header, ensuring only authorized owners can modify their respective namespaces.
• Transactional Integrity: Utilizes ultimate_db transactional handles to ensure atomic state changes and avoid race conditions.
• Dynamic UI Customization: Allows domain owners to persist custom branding (colors, logos, form actions) associated with their domain, which can be retrieved for portal bootstrap loading.
• TLD Governance: Prevents namespace collisions and enforces normalized domain formatting through standardized registration boundaries.

Architecture

The system operates as an engine sitting between an external identity provider and the core database:

Usage

Engine Initialization

The engine requires an existing ultimate_db.DB instance and a secure_dns.SecureDNS service to function.

engine := secure_registrar.NewRegistrarEngine(dbInstance, dnsService)

Routing

The package exports a helper to mount standard HTTP routes to your web framework:

// Assuming 'module' implements the RouteModule interface
secure_registrar.MountRegistrarRoutes(module, engine)

Identity-Based Operations

All secure endpoints expect the owner's public key in the request header. Here is an example of updating a domain's UI configuration:

// POST /registry/ui/layout
// Header: X-Identity-Public-Key: <your-public-key>
// Body: { "brand_name": "My Company", "primary_color": "#000000", ... }

Data Schema

The system relies on JSON-serialized metadata for governance:

• DomainMetadata: Tracks the ownership, hierarchy, and registration timestamp for any given domain.
• UIConfig: Stores dynamic branding information, including custom UI fields and button behaviors.

Testing

The package includes an extensive test suite in engine_test.go that utilizes a mock database to simulate various scenarios, including:

• Boundaries: Validation of TLD normalization and dot-character restrictions.
• Hierarchy: Verification that root domains cannot be registered without a pre-configured parent TLD.
• Security: Assertion that unauthorized keys cannot branch subdomains or modify configurations of domains they do not own.

To run the tests:

go test -v ./secure_registrar/...

License

This project is licensed under the MIT License.

Documentation

Index

• Constants
• Variables
• func IsICANNDelegatedTLD(label string) bool
• func IsIntentionalPrivateOverlay(label string) bool
• func MountRegistrarRoutes(module RouteModule, engine *RegistrarEngine)
• func ValidatePrivateTLD(tld string) error
• type DomainMetadata
• type RegistrarEngine
  • func NewRegistrarEngine(database *ultimate_db.DB, dnsService *secure_dns.SecureDNS) *RegistrarEngine
  • func (re *RegistrarEngine) EnsureRootDomain(domain, ownerPub string) error
  • func (re *RegistrarEngine) EnsureTLD(tld, adminPub string) error
  • func (re *RegistrarEngine) GetOwnership(domain string) (*DomainMetadata, error)
  • func (re *RegistrarEngine) ListDomains() ([]DomainMetadata, error)
  • func (re *RegistrarEngine) ListPrivateTLDs() ([]string, error)
  • func (re *RegistrarEngine) LockPlatformZone(domain string) error
  • func (re *RegistrarEngine) MaintainResourceRecord(callerPub, domain, recordType, value string, ttl int) error
  • func (re *RegistrarEngine) RegisterRootDomain(domain, ownerPub string) error
  • func (re *RegistrarEngine) RegisterSubdomain(subdomain, ownerPub string) error
  • func (re *RegistrarEngine) RegisterTLD(tld, adminPub string) error
  • func (re *RegistrarEngine) TransferOwnership(_, _, _ string) error
  • func (re *RegistrarEngine) UpdateUIConfig(callerPub, domain string, cfg UIConfig) error
• type RegistrarHandler
  • func (h *RegistrarHandler) HandleLookup(w http.ResponseWriter, req *http.Request)
  • func (h *RegistrarHandler) HandleMaintainDNS(w http.ResponseWriter, req *http.Request)
  • func (h *RegistrarHandler) HandleRegisterDomain(w http.ResponseWriter, req *http.Request)
  • func (h *RegistrarHandler) HandleRegisterSubdomain(w http.ResponseWriter, req *http.Request)
  • func (h *RegistrarHandler) HandleRegisterTLD(w http.ResponseWriter, req *http.Request)
  • func (h *RegistrarHandler) HandleSaveLayout(w http.ResponseWriter, req *http.Request)
  • func (h *RegistrarHandler) HandleTransfer(w http.ResponseWriter, req *http.Request)
• type RouteModule
• type UIButton
• type UIConfig
  • func DefaultConfig() UIConfig
• type UIField

Constants

const (
	RegistryPageID ultimate_db.PageID = 54
	ConfigPageID   ultimate_db.PageID = 55
)

const (
	LockPolicyPlatform = "platform" // no ownership transfer; NS/DS glue immutable via API
)

Lock policy labels stored on DomainMetadata.LockPolicy.

Variables

var (
	ErrTransferDisabled = fmt.Errorf("domain transfers are disabled on this registry")
	ErrGlueLocked       = fmt.Errorf("NS/DS glue records are locked for this zone")
)

Functions

func IsICANNDelegatedTLD

func IsICANNDelegatedTLD(label string) bool

IsICANNDelegatedTLD reports whether label is treated as public-root / ICANN space for the purpose of blocking accidental private registration. Intentional product overlays return false so they remain registerable.

func IsIntentionalPrivateOverlay

func IsIntentionalPrivateOverlay(label string) bool

IsIntentionalPrivateOverlay reports product TLDs allowed despite public-root collision.

func MountRegistrarRoutes

func MountRegistrarRoutes(module RouteModule, engine *RegistrarEngine)

func ValidatePrivateTLD

func ValidatePrivateTLD(tld string) error

ValidatePrivateTLD checks that tld may be registered as a private mesh extension: single LDH DNS label, not an unintended ICANN collision, not special-use reserved. Any non-ICANN TLD that passes label rules is allowed (open namespace).

Types

type DomainMetadata

type DomainMetadata struct {
	Domain       string    `json:"domain"`
	OwnerPub     string    `json:"owner_pub"`
	ParentDomain string    `json:"parent_domain"`
	RegisteredAt time.Time `json:"registered_at"`
	LockPolicy   string    `json:"lock_policy,omitempty"`
}

type RegistrarEngine

type RegistrarEngine struct {
	// contains filtered or unexported fields
}

func NewRegistrarEngine

func NewRegistrarEngine(database *ultimate_db.DB, dnsService *secure_dns.SecureDNS) *RegistrarEngine

func (*RegistrarEngine) EnsureRootDomain

func (re *RegistrarEngine) EnsureRootDomain(domain, ownerPub string) error

EnsureRootDomain registers a root zone if not already present (idempotent bootstrap).

func (*RegistrarEngine) EnsureTLD

func (re *RegistrarEngine) EnsureTLD(tld, adminPub string) error

EnsureTLD registers a private TLD if not already present (idempotent bootstrap). Any non-ICANN TLD is accepted; ICANN-delegated labels are rejected (see ValidatePrivateTLD).

func (*RegistrarEngine) GetOwnership

func (re *RegistrarEngine) GetOwnership(domain string) (*DomainMetadata, error)

func (*RegistrarEngine) ListDomains

func (re *RegistrarEngine) ListDomains() ([]DomainMetadata, error)

func (*RegistrarEngine) ListPrivateTLDs

func (re *RegistrarEngine) ListPrivateTLDs() ([]string, error)

ListPrivateTLDs returns registered single-label TLDs (parent empty, no dots).

func (*RegistrarEngine) LockPlatformZone

func (re *RegistrarEngine) LockPlatformZone(domain string) error

LockPlatformZone marks a zone as platform-operated: ownership cannot transfer and NS/DS records cannot be changed through MaintainResourceRecord (bootstrap paths write glue directly via secure_dns).

func (*RegistrarEngine) MaintainResourceRecord

func (re *RegistrarEngine) MaintainResourceRecord(callerPub, domain, recordType, value string, ttl int) error

func (*RegistrarEngine) RegisterRootDomain

func (re *RegistrarEngine) RegisterRootDomain(domain, ownerPub string) error

func (*RegistrarEngine) RegisterSubdomain

func (re *RegistrarEngine) RegisterSubdomain(subdomain, ownerPub string) error

func (*RegistrarEngine) RegisterTLD

func (re *RegistrarEngine) RegisterTLD(tld, adminPub string) error

func (*RegistrarEngine) TransferOwnership

func (re *RegistrarEngine) TransferOwnership(_, _, _ string) error

TransferOwnership is intentionally unsupported — registry leases are permanent.

func (*RegistrarEngine) UpdateUIConfig

func (re *RegistrarEngine) UpdateUIConfig(callerPub, domain string, cfg UIConfig) error

type RegistrarHandler

type RegistrarHandler struct {
	Engine *RegistrarEngine
}

func (*RegistrarHandler) HandleLookup

func (h *RegistrarHandler) HandleLookup(w http.ResponseWriter, req *http.Request)

func (*RegistrarHandler) HandleMaintainDNS

func (h *RegistrarHandler) HandleMaintainDNS(w http.ResponseWriter, req *http.Request)

func (*RegistrarHandler) HandleRegisterDomain

func (h *RegistrarHandler) HandleRegisterDomain(w http.ResponseWriter, req *http.Request)

func (*RegistrarHandler) HandleRegisterSubdomain

func (h *RegistrarHandler) HandleRegisterSubdomain(w http.ResponseWriter, req *http.Request)

func (*RegistrarHandler) HandleRegisterTLD

func (h *RegistrarHandler) HandleRegisterTLD(w http.ResponseWriter, req *http.Request)

func (*RegistrarHandler) HandleSaveLayout

func (h *RegistrarHandler) HandleSaveLayout(w http.ResponseWriter, req *http.Request)

func (*RegistrarHandler) HandleTransfer

func (h *RegistrarHandler) HandleTransfer(w http.ResponseWriter, req *http.Request)

type RouteModule

type RouteModule interface {
	Public(pattern string, handler http.HandlerFunc)
	Secure(pattern string, handler http.HandlerFunc)
}

type UIButton

type UIButton struct {
	Label   string `json:"label"`
	Type    string `json:"type"`
	Primary bool   `json:"primary"`
	OnClick string `json:"on_click"`
}

type UIConfig

type UIConfig struct {
	BrandName    string     `json:"brand_name"`
	PrimaryColor string     `json:"primary_color"`
	Logo         string     `json:"logo"`
	Description  string     `json:"description"`
	FormAction   string     `json:"form_action"`
	Fields       []UIField  `json:"fields"`
	Buttons      []UIButton `json:"buttons"`
}

func DefaultConfig

func DefaultConfig() UIConfig

type UIField

type UIField struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Type        string `json:"type"`
	Placeholder string `json:"placeholder"`
}