x/motr-enclave

Fork 0

Files

Prad Nukala 13cb35bc73 docs(network): add ipns architecture with cloudflare gateway integration

2026-01-11 12:30:05 -05:00

12 KiB

Raw Permalink Blame History

Network Architecture: IPNS DNSLink + Cloudflare IPFS Gateway

Integration guide for Sonr's decentralized storage layer using IPNS DNSLink with Cloudflare's enterprise IPFS gateway.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         SONR NETWORK TOPOLOGY                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────┐                    ┌─────────────────────────────┐ │
│  │   Browser Client    │                    │   Cloudflare Edge (330+)    │ │
│  │                     │      HTTPS         │                             │ │
│  │  vault.sonr.org ────┼───────────────────►│  IPFS Gateway + CDN Cache   │ │
│  │                     │                    │                             │ │
│  └─────────────────────┘                    └──────────────┬──────────────┘ │
│           │                                                │                │
│           │ Circuit Relay                                  │ Bitswap       │
│           ▼                                                ▼                │
│  ┌─────────────────────┐                    ┌─────────────────────────────┐ │
│  │   Sonr Relay Node   │◄──────────────────►│       IPFS Network          │ │
│  │   relay.sonr.org    │      P2P/DHT       │                             │ │
│  │                     │                    │  • Content Discovery        │ │
│  │  • Helia + Coord    │                    │  • Block Exchange           │ │
│  │  • IPNS Publishing  │                    │  • DHT Routing              │ │
│  └─────────────────────┘                    └─────────────────────────────┘ │
│           │                                                                 │
│           │ IPNS Publish                                                    │
│           ▼                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      Cloudflare DNS (sonr.org)                      │   │
│  │                                                                     │   │
│  │   _dnslink.vault.sonr.org  TXT  "dnslink=/ipns/<PEER_ID>"          │   │
│  │   vault.sonr.org           CNAME cloudflare-ipfs.com (proxied)     │   │
│  │                                                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

Cloudflare Enterprise Features

Plan Comparison

Feature	Free/Pro/Business	Enterprise
Total Gateways	15	Unlimited
Gateway Types	DNSLink only	DNSLink + Universal Path
Included Bandwidth	50 GB	100 GB
File Size Limit	None	None
SLA	Standard	Enterprise SLA
Support	Ticket	24/7 Dedicated
Peering Priority	Standard	Custom peering configuration

Enterprise Benefits

Benefit	Description
Unlimited Gateways	No limit on custom domain gateways
Universal Path Gateway	Access any CID via `gateway.sonr.org/ipfs/<CID>`
Custom Peering	Direct peering with Sonr relay nodes
Edge Caching	330+ PoPs, automatic cache invalidation on IPNS update
Origin Isolation	XSS protection via subdomain isolation

DNS Configuration

Required Records

Type	Name	Value	Proxy
CNAME	`vault.sonr.org`	`cloudflare-ipfs.com`	Proxied
TXT	`_dnslink.vault.sonr.org`	`dnslink=/ipns/<PEER_ID>`	N/A
CNAME	`gateway.sonr.org`	`cloudflare-ipfs.com`	Proxied
TXT	`_dnslink.gateway.sonr.org`	`dnslink=/ipns/<PEER_ID>`	N/A

DNSLink Format

dnslink=/ipns/<PEER_ID>
dnslink=/ipns/<DOMAIN>
dnslink=/ipfs/<CID>

Format	Use Case
`/ipns/<PEER_ID>`	Mutable content, updates without DNS change
`/ipns/<DOMAIN>`	Recursive resolution to another DNSLink
`/ipfs/<CID>`	Immutable content, requires DNS update

Verification

dig +short TXT _dnslink.vault.sonr.org

Gateway Types

DNSLink Gateway (Restricted)

Serves content from a single IPNS/CID specified in DNS.

https://vault.sonr.org/
    └── Resolves _dnslink.vault.sonr.org
        └── /ipns/k51qzi5uqu5...
            └── /ipfs/bafy...

Universal Path Gateway (Enterprise)

Serves any content by CID or IPNS path.

https://gateway.sonr.org/ipfs/<CID>
https://gateway.sonr.org/ipns/<PEER_ID>
https://gateway.sonr.org/ipns/<DOMAIN>

IPNS Publishing

Helia Integration

import { createHelia } from 'helia'
import { ipns } from '@helia/ipns'
import { unixfs } from '@helia/unixfs'
import { generateKeyPair } from '@libp2p/crypto/keys'

const helia = await createHelia()
const name = ipns(helia)
const fs = unixfs(helia)

const cid = await fs.addBytes(encryptedEnclaveBlob)

await name.publish(privateKey, cid, {
  lifetime: 24 * 60 * 60 * 1000
})

DNSLink Resolution

import { dnsLink } from '@helia/dnslink'

const resolver = dnsLink(helia)
const result = await resolver.resolve('vault.sonr.org')

TTL Configuration

DNS TTL

Use Case	TTL	Rationale
Frequently updated content	60s	Fast propagation
Stable content	3600s	Reduce DNS queries
Production default	300s	Balance between freshness and efficiency

IPNS Lifetime

Parameter	Value	Description
`lifetime`	24h	Record validity period
`ttl`	1h	Suggested cache duration for resolvers

await name.publish(privateKey, cid, {
  lifetime: 24 * 60 * 60 * 1000,
  ttl: 60 * 60 * 1000
})

Cloudflare API Integration

Create Web3 Gateway

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/web3/hostnames" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "vault.sonr.org",
    "description": "Sonr Vault IPFS Gateway",
    "target": "ipfs",
    "dnslink": "/ipns/<PEER_ID>"
  }'

Update DNSLink

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/web3/hostnames/{gateway_id}" \
  --request PATCH \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "dnslink": "/ipns/<NEW_PEER_ID>"
  }'

Create TXT Record

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "TXT",
    "name": "_dnslink.vault.sonr.org",
    "content": "dnslink=/ipns/<PEER_ID>",
    "ttl": 300
  }'

Domain Strategy

Subdomain Allocation

Subdomain	Type	Purpose
`vault.sonr.org`	DNSLink	User enclave data (IPNS)
`did.sonr.org`	DNSLink	DID document resolution (IPNS)
`gateway.sonr.org`	Universal	General IPFS access (Enterprise)
`relay.sonr.org`	Direct	Circuit Relay server (WSS)

Resolution Flow

User Request: https://vault.sonr.org/
    │
    ▼
Cloudflare Edge
    │
    ├── Check edge cache
    │   └── Hit: Return cached content
    │
    ├── DNS Lookup: _dnslink.vault.sonr.org
    │   └── TXT: dnslink=/ipns/k51qzi5uqu5...
    │
    ├── IPNS Resolution
    │   └── k51qzi5uqu5... → /ipfs/bafy...
    │
    ├── IPFS Fetch (Bitswap)
    │   └── Retrieve blocks from network
    │
    └── Cache + Return

Caching Behavior

Edge Cache

Trigger	Action
First request	Fetch from IPFS, cache at edge
Subsequent requests	Serve from edge cache
IPNS update	Cache invalidated on TTL expiry
Manual purge	API-triggered cache clear

Cache Headers

Cache-Control: public, max-age=3600
X-IPFS-Path: /ipfs/bafy...
X-IPFS-Roots: bafy...
ETag: "bafy..."

Content Update Flow

Without DNS Change (IPNS)

1. Encrypt new enclave blob
2. Add to Helia: cid = await fs.addBytes(blob)
3. Publish IPNS: await name.publish(key, cid)
4. Cloudflare resolves new CID on next request (after TTL)

With DNS Change (CID)

1. Add content to IPFS
2. Update _dnslink TXT record via Cloudflare API
3. Wait for DNS propagation (TTL)
4. Cloudflare serves new content

Security

Transport Security

Layer	Protection
Client → Cloudflare	TLS 1.3
Cloudflare → IPFS	Bitswap (encrypted channels)
Content	AES-256-GCM (client-side)

Content Integrity

Mechanism	Guarantee
CID	SHA-256 hash of content
IPNS Signature	Ed25519 signed record
DNSLink	DNSSEC (if enabled)

Access Control

Method	Implementation
Private content	Encrypt before upload
Rate limiting	Cloudflare WAF rules
Blocklist	Universal gateway content filtering

Monitoring

Cloudflare Analytics

Metric	Source
Requests	Web3 Gateway dashboard
Bandwidth	Zone analytics
Cache hit ratio	Cache analytics
Error rates	Firewall events

IPNS Health

const status = {
  peerId: helia.libp2p.peerId.toString(),
  peers: helia.libp2p.getPeers().length,
  ipnsRecords: await getPublishedRecords()
}

Implementation Checklist

Cloudflare Setup

Enable Web3 gateway on zone
Create DNSLink gateway for vault.sonr.org
Create DNSLink gateway for did.sonr.org
Create Universal gateway for gateway.sonr.org (Enterprise)
Configure TXT records for each subdomain
Verify CNAME proxying enabled
Set appropriate TTLs

Relay Node Setup

Deploy ipfs-service-provider with relay enabled
Generate persistent IPNS keypair
Configure IPNS publishing on content update
Set up monitoring for IPNS record health
Configure peering with Cloudflare (Enterprise)

SDK Integration

Add @helia/ipns for publishing
Add @helia/dnslink for resolution
Implement enclave CID tracking
Add IPNS publish on enclave save
Handle offline/online sync

Dependencies

{
  "@helia/ipns": "^8.0.0",
  "@helia/dnslink": "^4.0.0",
  "@helia/unixfs": "^4.0.0",
  "helia": "^5.0.0"
}

12 KiB Raw Permalink Blame History