[P8] Implement Web4 Domain & Content API methods (3 endpoints)

[umwelt]

Overview

Implement all Web4 domain and content API methods in the TypeScript client to match the ZHTP node's Web4 endpoints.

Related to: #17 - Comprehensive API Implementation Guide
Priority: P8 - MEDIUM-LOW (Nice to have, not critical for alpha)
Estimated Effort: Small (2-3 hours)

Background

The ZHTP node has 3 Web4 endpoints for decentralized domain management and content resolution:

• Domain registration
• Domain resolution
• Content retrieval

Web4 is the sovereign network's decentralized DNS system, allowing users to register .zhtp domains that resolve to DIDs and content.

Required Methods

Domain Registration (1 endpoint)

1. registerWeb4Domain() ❌ MISSING

Endpoint: POST /api/v1/web4/register

Request:

{
  domain: string, // e.g., "mysite.zhtp"
  owner_did: string,
  content_hash?: string, // Optional content CID
  ttl?: number // Time to live in seconds
}

Expected Response:

{
  status: "success",
  domain: "mysite.zhtp",
  owner: "did:zhtp:...",
  content_hash: "Qm...",
  registration_tx: "...",
  expires_at: 1234567890
}

Action: Implement new method

Use Cases:

• Register a domain for a personal website
• Link domain to DID for identity resolution
• Associate domain with IPFS/content hash

Domain Resolution (1 endpoint)

2. resolveWeb4Domain() ❌ MISSING

Endpoint: GET /api/v1/web4/resolve/{domain}

Example: GET /api/v1/web4/resolve/mysite.zhtp

Expected Response:

{
  status: "success",
  domain: "mysite.zhtp",
  owner: "did:zhtp:...",
  content_hash: "Qm...",
  registered_at: 1234567890,
  expires_at: 1734567890,
  ttl: 3600
}

Action: Implement new method

Use Cases:

• Resolve domain to DID for identity lookup
• Resolve domain to content hash for website access
• Check domain ownership and expiration

Content Retrieval (1 endpoint)

3. getWeb4Content() ❌ MISSING

Endpoint: GET /api/v1/web4/content/{domain}

Example: GET /api/v1/web4/content/mysite.zhtp

Expected Response:

{
  status: "success",
  domain: "mysite.zhtp",
  content_hash: "Qm...",
  content: "...", // Base64 encoded or raw content
  content_type: "text/html",
  size: 1024
}

Action: Implement new method

Use Cases:

• Fetch website content for rendering
• Retrieve decentralized content by domain name
• Build Web4 browser or viewer

Implementation Checklist

Phase 1: Implement Methods

• Implement registerWeb4Domain()
• Implement resolveWeb4Domain()
• Implement getWeb4Content()

Phase 2: Type Definitions

• Define Web4Domain type
• Define Web4RegistrationRequest type
• Define Web4ResolveResponse type
• Define Web4ContentResponse type

Phase 3: Testing

• Test domain registration (use testnet!)
• Test domain resolution
• Test content retrieval
• Test error handling:
  • Domain already registered
  • Domain not found
  • Invalid domain format
  • Content not available
• Test domain expiration logic

Phase 4: Documentation

• Add JSDoc comments to all methods
• Document Web4 domain naming rules
• Create usage examples:
  • Register and manage domains
  • Build a Web4 browser
  • Resolve domains to DIDs
• Update main README with Web4 examples

Files to Modify

• src/core/zhtp-api-methods.ts - Add Web4 methods
• src/core/types.ts - Add Web4-related type definitions
• src/core/zhtp-api-client.ts - Export new methods

Success Criteria

• All 3 Web4 endpoints have corresponding TypeScript methods
• All methods use /api/v1 paths
• Response types match node implementation
• All methods handle errors properly
• Full test coverage for Web4 functionality
• Documentation complete with usage examples

Use Cases

Register a Web4 Domain

// Register a domain for your identity
const registration = await client.registerWeb4Domain({
  domain: "alice.zhtp",
  owner_did: "did:zhtp:abc123",
  content_hash: "QmYourContentHash",
  ttl: 86400 // 24 hours
});

console.log(`Domain registered: ${registration.domain}`);
console.log(`Expires: ${new Date(registration.expires_at * 1000)}`);

Resolve a Domain

// Resolve a domain to find the owner and content
const resolved = await client.resolveWeb4Domain("alice.zhtp");

console.log(`Owner: ${resolved.owner}`);
console.log(`Content: ${resolved.content_hash}`);

Build a Web4 Browser

// Fetch and display Web4 content
async function loadWeb4Site(domain: string) {
  const content = await client.getWeb4Content(domain);
  
  if (content.content_type === "text/html") {
    // Decode and render HTML
    const html = atob(content.content);
    document.body.innerHTML = html;
  }
}

loadWeb4Site("mysite.zhtp");

Check Domain Availability

// Check if a domain is available
async function isDomainAvailable(domain: string): Promise<boolean> {
  try {
    await client.resolveWeb4Domain(domain);
    return false; // Domain exists
  } catch (error) {
    if (error.status === 404) {
      return true; // Domain available
    }
    throw error; // Other error
  }
}

const available = await isDomainAvailable("newdomain.zhtp");
console.log(available ? "Available!" : "Already taken");

Domain Naming Rules

Based on typical DNS conventions, Web4 domains should follow these rules:

• Format: {name}.zhtp
• Name constraints:
  • Lowercase letters (a-z)
  • Numbers (0-9)
  • Hyphens (-) but not at start/end
  • Length: 3-63 characters
• Reserved domains:
  • System domains (e.g., api.zhtp, www.zhtp)
  • Protocol domains (e.g., protocol.zhtp)

TODO: Verify these rules with the node implementation and add validation to client methods.

Priority Rationale

Web4 functionality is important for decentralized web hosting but not critical for the initial alpha release:

• Lower Priority Than: Identity, wallet, DAO, guardians, ZK proofs
• Important For: Decentralized websites, content hosting, DNS replacement
• Can Be Deferred: Users can still use the platform without Web4 domains

However, it's still worth implementing since:

1. It's only 3 endpoints (small effort)
2. It showcases the platform's decentralization features
3. It enables interesting use cases (decentralized websites)

Dependencies

• Session authentication (already implemented)
• Identity management (already implemented)
• Transaction signing (for domain registration)
• Content storage system (for content retrieval)
• Error handling utilities (already implemented)

Related Issues

• [IMPLEMENTATION GUIDE] Complete ZHTP Node API Endpoint Reference #17 - Parent issue: Complete API Implementation Guide
• Node issue [META] Missing API endpoints - Tracking Issue The-Sovereign-Network#112 (closed - all endpoints implemented)

Testing Notes

Domain Registration: Use testnet for testing domain registration to avoid polluting mainnet with test domains. Consider implementing domain renewal and transfer functionality in the future.

Content Retrieval: Large content may need streaming or chunking. Consider size limits and performance optimization for content retrieval.

Future Enhancements (Post-Alpha)

• Domain transfer/sale functionality
• Domain renewal
• Subdomain support
• DNS record types (A, CNAME, TXT, etc.)
• Domain marketplace
• ENS/DNS bridge for Web2 compatibility