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

EndpointMethodeBeschrijvingAuth
/ipfs/pinPOSTContent uploaden en pinnen op IPFSSession cookie
/ipfs/:cidGETContent ophalen via IPFS gateway proxyGeen (publiek)
/ipfs/status/:cidGETPin-status controlerenSession cookie
/ipfs/unpin/:cidDELETEContent verwijderen van IPFSSession + 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

FormaatVoorbeeldGebruik
CIDv0QmXoypiz...LEzLegacy, SHA-256
CIDv1bafybeig...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

10. Risico's en aanbevelingen

RisicoImpactMitigatie
IPFS gateway onbereikbaarHighMulti-gateway fallback: ipfs.io → cloudflare → dweb.link. Timeout per gateway: 10s.
Pin-falen bij externe providersMediumRetry met exponential backoff. Minimaal 1 succesvolle pin vereist.
Grote bundles (>100MB)MediumChunked upload naar Kubo. Geen volledige bundel in geheugen.
Cache-uitbraak bij SW updateLowVersioned cache keys. SW update → oude cache verwijderen.
Kubo node niet beschikbaarHighHealth 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).