API: IPFS pin + gateway
Ticket 1B-02 • Bron: src/routes/ipfs.ts (gepland) • Status: ontwerp • Risico: hoog (netwerk-afhankelijk)
Kerndefinitie: IPFS-integratie in twee delen: (1) Pin-routes voor het uploaden en vastleggen van content op IPFS, en (2) Gateway-proxy voor het ophalen van content via IPFS gateways met CORS-ondersteuning en service-worker cache-hit optimalisatie. CID-verificatie via hash-match garandeert integriteit.
1. Architectuur
Client / DApp
│
├── POST /ipfs/pin
│ ├── Upload content (multipart)
│ ├── CID berekenen (SHA-256 / CIDv1)
│ ├── Pin bij Kubo node
│ ├── Pin bij externe providers (optioneel)
│ └── return { cid, size, pinned }
│
├── GET /ipfs/:cid
│ ├── CID validatie (geldig IPFS CID?)
│ ├── Gateway proxy fetch
│ ├── CORS headers instellen
│ ├── Content-Type detectie
│ └── Stream response naar client
│
└── Service Worker
├── Cache-first strategie
├── Cache-hit? → direct uit cache
└── Cache-miss? → gateway proxy + cache opslaan
Kubo node (self-hosted):
├── /api/v0/add (pin upload)
├── /api/v0/cat (content ophalen)
└── /api/v0/pin/add (vastleggen)
2. Endpoints
| Endpoint | Methode | Beschrijving | Auth |
/ipfs/pin | POST | Content uploaden en pinnen op IPFS | Session cookie |
/ipfs/:cid | GET | Content ophalen via IPFS gateway proxy | Geen (publiek) |
/ipfs/status/:cid | GET | Pin-status controleren | Session cookie |
/ipfs/unpin/:cid | DELETE | Content verwijderen van IPFS | Session + eigenaar |
3. CID-verificatie (hash-match)
Ontvangen content + verwachte CID
│
├── 1. Content hash berekenen
│ ├── SHA-256 van content bytes
│ └── CIDv1 formát: bafybeig...
│
├── 2. Vergelijk met opgegeven CID
│ ├── Hash match? → geldig
│ └── Geen match? → reject (corruptie of manipulatie)
│
└── 3. Pin alleen bij geldige CID
└── Kubo: /api/v0/pin/add?arg=
3.1 CID-formaten
| Formaat | Voorbeeld | Gebruik |
| CIDv0 | QmXoypiz...LEz | Legacy, SHA-256 |
| CIDv1 | bafybeig... | Modern, meerdere hash-functies |
4. Pin-flow
POST /ipfs/pin
│
├── 1. Content ontvangen (multipart/form-data)
│ ├── field: "file" (binary)
│ └── optioneel: "expectedCid" (verificatie)
│
├── 2. CID berekenen
│ ├── Content → SHA-256 → CIDv1
│ └── Optioneel: vergelijk met expectedCid
│
├── 3. Pin bij Kubo node
│ ├── POST http://localhost:5001/api/v0/add
│ ├── Body: multipart met file
│ └── Response: { Name: "cid", Size: "1234" }
│
├── 4. Pin bij externe providers (optioneel)
│ ├── Pinata: POST /pinning/pinFileToIPFS
│ ├── Infura: POST /api/v0/add
│ └── Minimaal 1 externe provider voor redundancy
│
└── 5. Response
{
"cid": "bafybeig...",
"size": 12345,
"pinned": ["kubo", "pinata"],
"verified": true
}
5. Gateway proxy
GET /ipfs/:cid
│
├── 1. CID validatie
│ ├── Is geldig IPFS CID? (v0 of v1)
│ └── Nee → 400 { error: "Invalid CID" }
│
├── 2. Service Worker cache check
│ ├── Cache-hit? → return uit cache (geen netwerk)
│ └── Cache-miss? → door naar gateway
│
├── 3. Gateway fetch
│ ├── Fetch van: https://ipfs.io/ipfs/{cid}
│ ├── Of: https://{cid}.ipfs.dweb.link
│ └── Timeout: 30 seconden
│
├── 4. Response streamen
│ ├── CORS headers: Access-Control-Allow-Origin: *
│ ├── Content-Type: uit gateway response
│ ├── Cache-Control: public, max-age=31536000, immutable
│ └── Stream body naar client
│
└── 5. Cache opslaan
└── SW slaat response op voor toekomstige verzoeken
6. CORS-configuratie
Gateway proxy response headers:
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Headers: Range, Content-Type
Access-Control-Expose-Headers: Content-Length, Content-Range
Access-Control-Max-Age: 86400
REDEN: DApps in iframes moeten IPFS-content kunnen laden.
Zonder CORS blokkeren browsers de response.
7. Service Worker cache-strategie
Cache-first ( immutable content):
1. Fetch event intercepteren
2. Cache.match(key = request.url)
3. Cache-hit? → return cached response
4. Cache-miss? → fetch → cache.put → return
Cache-sleutel: volledige URL (https://maos.dedyn.io/ipfs/{cid})
TTL: geen (IPFS-content is immutable — CID verandert niet)
Max cache-grootte: 50MB (LRU eviction)
8. Request / Response voorbeelden
8.1 POST /ipfs/pin
POST /ipfs/pin HTTP/1.1
Content-Type: multipart/form-data; boundary=...
--boundary
Content-Disposition: form-data; name="file"; filename="dapp-bundle.tar.gz"
Content-Type: application/gzip
[binary data]
--boundary--
Response:
{
"cid": "bafybeig5zag3...",
"size": 1048576,
"pinned": ["kubo", "pinata"],
"verified": true
}
8.2 GET /ipfs/:cid
GET /ipfs/bafybeig5zag3... HTTP/1.1
Response (binary stream):
Content-Type: application/gzip
Cache-Control: public, max-age=31536000, immutable
Content-Length: 1048576
[binary data stream]
8.3 Foutafhandeling
// Ongeldige CID
GET /ipfs/not-a-valid-cid HTTP/1.1
→ 400 { "error": "Invalid CID", "cid": "not-a-valid-cid" }
// Gateway timeout
GET /ipfs/bafybeig... HTTP/1.1
→ 504 { "error": "Gateway timeout", "cid": "bafybeig..." }
// Pin mislukt
POST /ipfs/pin HTTP/1.1
→ 500 { "error": "Pin failed", "details": "Kubo unreachable" }
9. Acceptatiecriteria
- CID-verificatie: hash-match met content. Ongeldige CID = reject.
- Pin endpoint: content uploaden + Kubo pin + response met CID
- Gateway proxy: CORS headers + content streamen
- Service Worker: cache-hit voorkomt netwerkverzoeken
- Immutable caching: IPFS-content = immutable, max-age=1 jaar
- Multi-provider: pin bij minimaal 2 providers (Kubo + 1 extern)
- Timeout handling: 30s timeout op gateway fetch
10. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| IPFS gateway onbereikbaar | High | Multi-gateway fallback: ipfs.io → cloudflare → dweb.link. Timeout per gateway: 10s. |
| Pin-falen bij externe providers | Medium | Retry met exponential backoff. Minimaal 1 succesvolle pin vereist. |
| Grote bundles (>100MB) | Medium | Chunked upload naar Kubo. Geen volledige bundel in geheugen. |
| Cache-uitbraak bij SW update | Low | Versioned cache keys. SW update → oude cache verwijderen. |
| Kubo node niet beschikbaar | High | Health check op startup. Fallback naar externe providers-only modus. |
11. Verwijzingen
Fase 1B Nog niet geimplementeerd. Vereist: Kubo RPC client, Service Worker implementatie, multi-gateway config. Prioriteit: hoog (blokkeert DApp-publishing).