IPFS gateway

Private trustless gateways • gateway-allowlist • verified-fetch in Service Worker • hash-verificatie bij elke fetch • cache-strategie (immutable = oneindig, mutable = 5 min) • geen publieke fallback • status: ontwerp, nog geen code

Kerndefinitie: De IPFS gateway-laag biedt verified content delivery via private trustless gateways. Elke fetch wordt geverifieerd op hash-integriteit. Er worden geen publieke gateways gebruikt. De Service Worker handhaaft de cache-strategie: immutable CIDs forever, mutable pointers (IPNS) 5 minuten TTL.

1. Architectuur-overzicht

┌─────────────────────────────────────────────────────────────┐
│                   IPFS Gateway Manager                      │
│                                                              │
│  ┌──────────────────┐    ┌──────────────────┐              │
│  │  Gateway Router  │    │  Hash Verifier   │              │
│  │                  │    │                  │              │
│  │  fetch(CID)      │    │  verify(bytes,   │              │
│  │  selectGateway() │    │    CID)          │              │
│  │  rotateGateway() │    │                  │              │
│  └────────┬─────────┘    └────────┬─────────┘              │
│           │                       │                         │
│  ┌────────▼───────────────────────▼─────────┐              │
│  │           Gateway Allowlist               │              │
│  │  [Kubo Primary, Provider A, Provider B]  │              │
│  └────────┬───────────┬───────────┬─────────┘              │
│           │           │           │                         │
│  ┌────────▼───┐ ┌─────▼─────┐ ┌──▼──────────┐            │
│  │  Kubo      │ │ Provider A│ │ Provider B  │            │
│  │  Primary   │ │ (extern)  │ │ (extern)    │            │
│  └────────────┘ └───────────┘ └─────────────┘            │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           Service Worker (verified-fetch)            │   │
│  │  fetch() → verify() → cache() → return              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Helia Cache (lokaal)                    │   │
│  │  immutable: oneindig | mutable: 5 min TTL          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

2. Private trustless gateways

2.1 Gateway-allowlist

GatewayLocatieTypeRol
Kubo PrimaryHono-serverEigen nodePrimaire gateway. Volledige IPFS-node. Preferentie bij elke fetch.
Kubo ReplicaBackup-serverEigen nodeBackup. Alleen bij falen Primary.
Provider ACloudExtern (Pinning Service)Externe gateway. Fallback na eigen nodes.
Provider BCloudExtern (Pinning Service)Externe gateway. Tweede fallback.

2.2 Gateway-selectie

gatewayRouter.selectGateway(cid, tier)
    │
    ├── 1. Preferentie: Kubo Primary
    │       ├── Beschikbaar? → gebruik
    │       └── Niet beschikbaar? → ga naar stap 2
    │
    ├── 2. Fallback: Kubo Replica
    │       ├── Beschikbaar? → gebruik
    │       └── Niet beschikbaar? → ga naar stap 3
    │
    ├── 3. Fallback: Provider A
    │       ├── Beschikbaar? → gebruik
    │       └── Niet beschikbaar? → ga naar stap 4
    │
    └── 4. Fallback: Provider B
            ├── Beschikbaar? → gebruik
            └── Niet beschikbaar? → error: "Geen beschikbare gateway"
VEILIGHEIDSREGEL: MAOS gebruikt nooit publieke IPFS-gateways (ipfs.io, cloudflare-ipfs, dweb.link, enz.). Alleen private trustless gateways die door MAOS beheerd of goedgekeurd zijn. Als alle private gateways uitvallen: content niet beschikbaar, geen fallback.

2.3 Redenen geen publieke gateways

3. Verified-fetch in Service Worker

3.1 Fetch-flow

SW ontvangt fetch-verzoek (CID)
    │
    ├── 1. Check Helia-lokaal (cache)
    │       │
    │       ├── Hit → hash-verificatie → return (zero-network)
    │       │
    │       └── Miss → ga naar stap 2
    │
    ├── 2. Gateway-allowlist check
    │       │
    │       ├── Kubo Primary (preferentie)
    │       │
    │       └── Andere private trustless gateways (fallback)
    │
    ├── 3. Fetch raw block of CAR
    │       │
    │       ├── Raw block: GET /ipfs/{cid}
    │       └── CAR archive: GET /ipfs/{cid}?format=car
    │
    ├── 4. Hash-verificatie (bytes !== = reject)
    │       │
    │       ├── Hash berekenen van ontvangen data
    │       │   SHA-256(bytes) → berekende_hash
    │       │
    │       ├── Vergelijk met CID-multihash
    │       │   CID.multihash → verwachte_hash
    │       │
    │       ├── Match? → door naar stap 5
    │       └── Geen match? → REJECT + audit-log
    │
    ├── 5. Pin in Helia-lokaal (voor volgende keer)
    │
    └── 6. Return response

3.2 Verificatie-regels

RegelBeschrijvingBij falen
Hash-matchBij elke fetch wordt de hash van de ontvangen data geverifieerd tegen de CID. SHA-256.Reject + audit + geen cache
Geen publieke gatewaysAlleen private trustless gateways in allowlist. Geen ipfs.io, cloudflare-ipfs, enz.Request geweigerd
Geen fallbackAls private gateway niet bereikbaar is, probeer andere private gateway. Nooit terugvallen op publieke bronnen.Content niet beschikbaar
CAR vs raw blocksBij voorkeur CAR-archieven voor batch-ophaling. Raw blocks voor enkele items.Automatische selectie

3.3 CAR vs raw blocks

CAR (Content Addressable aRchive)
Voorkeur voor bundels met meerdere bestanden. Een CAR bevat alle blocks van een CID-tree. Efficiënter voor DApp-bundles (HTML + JS + CSS + assets).
Raw blocksVoor enkele bestanden. Eenvoudiger, minder overhead. Gebruikt voor individuele assets of kleine bestanden.

4. Cache-strategie

4.1 Cache-types

TypeCache-duurRedenImplementatie
Immutable CIDOneindigCID = content hash. Na verificatie = permanent geldig.IndexedDB (Helia) + SW-cache
Mutable pointer (IPNS)5 minutenKan wijzigen, frequente herverificatie.SW-cache met TTL
Gateway responsePer Cache-Control headersRespecteer gateway-instellingen.SW-cache

4.2 Immutable cache-regels

4.3 Mutable cache-regels

5. Gateway-allowlist beheer

5.1 Configuratie

{
  "gateways": [
    {
      "name": "kubo-primary",
      "url": "http://kubo.internal:8080",
      "preferred": true,
      "timeout": 5000,
      "retryCount": 2,
      "healthCheck": {
        "interval": 30000,
        "endpoint": "/api/v0/id"
      }
    },
    {
      "name": "kubo-replica",
      "url": "http://kubo-replica.internal:8080",
      "preferred": false,
      "timeout": 5000,
      "retryCount": 2
    },
    {
      "name": "provider-a",
      "url": "https://provider-a.example.com",
      "preferred": false,
      "timeout": 10000,
      "retryCount": 1,
      "auth": {
        "type": "bearer",
        "token": "{env:PROVIDER_A_TOKEN}"
      }
    }
  ],
  "defaultTimeout": 5000,
  "defaultRetryCount": 2,
  "maxConcurrentFetches": 10
}

5.2 Health-check

6. Service Worker integratie

6.1 SW-registratie

// In shell (main-thread)
navigator.serviceWorker.register('/sw-ipfs.js', { scope: '/' })
  .then(reg => {
    // SW is actief voor alle fetch-verzoeken
    console.log('IPFS SW geregistreerd');
  });

// SW: sw-ipfs.js
self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);

  // Alleen IPFS-verzoeken afvangen
  if (url.pathname.startsWith('/ipfs/')) {
    event.respondWith(verifiedFetch(url.pathname));
  }
});

6.2 Verified-fetch implementatie

async function verifiedFetch(path) {
  const cid = extractCID(path);  // /ipfs/bafy... → bafy...

  // 1. Check Helia-lokaal
  const cached = await helia.get(cid);
  if (cached) {
    const verified = await verifyHash(cached, cid);
    if (verified) return new Response(cached);
  }

  // 2. Gateway-allowlist
  for (const gateway of allowlist) {
    try {
      const response = await fetch(gateway.url + path, {
        signal: AbortSignal.timeout(gateway.timeout)
      });

      if (!response.ok) continue;

      const bytes = new Uint8Array(await response.arrayBuffer());

      // 3. Hash-verificatie
      const verified = await verifyHash(bytes, cid);
      if (!verified) {
        auditLog('hash-mismatch', cid, gateway.name);
        continue;  // probeer volgende gateway
      }

      // 4. Cache voor volgende keer
      await helia.pin(cid, bytes);

      return new Response(bytes);
    } catch (err) {
      continue;  // probeer volgende gateway
    }
  }

  // 5. Alle gateways gefaald
  return new Response('Content not available', { status: 503 });
}

7. Hash-verificatie detail

verifyHash(bytes, cid)
    │
    ├── 1. CID parsen
    │       ├── Multicodec: dag-pb of raw
    │       ├── Multihash: SHA-256 (0x12)
    │       └── Hash- bytes uit CID extraheren
    │
    ├── 2. Hash berekenen
    │       SHA-256(bytes) → berekende_hash
    │
    ├── 3. Vergelijken
    │       berekende_hash === verwachte_hash?
    │       │
    │       ├── Ja → return true (geldig)
    │       └── Nee → return false (ongeldig)
    │
    └── 4. Bij false: audit-log
            {
              event: "hash-mismatch",
              cid: "bafy...",
              gateway: "kubo-primary",
              timestamp: "2025-01-15T10:30:00Z",
              expected: "0x1220...",
              calculated: "0x1220..."
            }

8. Acceptatiecriteria

AC-3
#CriteriaMeting
AC-1Elke fetch wordt geverifieerd op hash-integriteitTest met gemanipuleerde data: reject
AC-2Immutable CIDs worden oneindig gecachetTest: tweede fetch = zero-network
Mutable pointers (IPNS) worden na 5 minuten herverifieerdTest: fetch na 6 min = opnieuw ophalen
AC-4Publieke gateways worden geweigerdTest: fetch naar ipfs.io = error
AC-5Bij gateway-faal: fallback naar volgende private gatewayTest: Primary down → Replica
AC-6Bij alle gateways falen: 503 response (geen publieke fallback)Test: alle gateways down = 503
AC-7Hash-mismatch wordt gedetecteerd en gelogdTest: gemanipuleerde data = audit-log

9. Risico's en aanbevelingen

RisicoImpactAanbeveling
Alle gateways falen gelijktijdighoogKubo Replica als tweede backup. Health-check detecteert falen snel.
Hash-mismatch door network-corruptiemiddelBij mismatch: gateway uit allowlist + herhaal fetch bij alternatieve gateway.
IPNS-resolutie langzaam (>5s)middelIPNS-cache met 5 min TTL. Bij langzame resolutie: gebruik laatst bekende CID.
Helia-cache loopt vol (geheugendruk)middelLRU-evictie + emergency cleanup bij geheugendruk.
Gateway-wijziging niet opgemerktlaagHealth-check elke 30s. Bij wijziging: automatische verwijdering uit allowlist.

10. Verwijzingen naar verwante specs

Volgende stap Na akkoord: SW implementatie (verified-fetch + cache) + Gateway Router + Hash Verifier + Helia-integratie + Gateway-allowlist config.

11. Grillvragen