IPFS pin + gateway

Eigen IPFS-gateway + Helia-cache • pin-strategie met multi-provider • verified-fetch in Service Worker • geen publieke fallback • status: ontwerp, nog geen code

Kerndefinitie: IPFS is de opslaglaag voor DApp-bundles, content en metadata. MAOS beheert een eigen trustless gateway + Helia-node voor lokale caching. Pinnen gebeurt bij minimaal 2-3 providers. Content wordt opgehaald via verified-fetch (hash-verificatie bij elke stap).

1. Eigen IPFS-gateway + Helia-cache

1.1 Architectuur

Service Worker ──verified-fetch(CID)──▶ Helia-lokaal (cache)
        │                                    │
        │                                    ├── Cache hit? ──▶ return (zero-network)
        │                                    │
        │                                    └── Cache miss ──▶ gateway-allowlist
        │                                                          │
        │                                                          ├── Eigen Kubo-node
        │                                                          ├── Pinning-provider A
        │                                                          └── Pinning-provider B
        │
        └── Hash-verificatie bij elke stap (bytes !== = reject)

1.2 Helia-node (lokaal)

1.3 Eigen Kubo-cluster

ComponentLocatieRol
Kubo-node (primary)Hono-serverVolledige IPFS-node voor pin + serve
Kubo-node (replica)Backup-serverReplicatie van kritieke CIDs (core, tier-0)
Helia (client)Service WorkerLokale cache + directe toegang

2. Pin-strategie (multi-provider)

2.1 Pin-regels per tier

TierAantal providersProvidersVerplicht
Tier-0 (core)3+Eigen Kubo + 2 externe pinning-servicesJa, altijd
Tier-1 (verified)2+Eigen Kubo + 1 externe pinning-serviceJa
Tier-2 (third-party)1+Minimaal 1 pinning-serviceJa (publisher verantwoordelijk)

2.2 Pin-flow

Publisher: maos publish
    │
    ├── Vite-build → bundle + manifest.json
    │
    ├── Ed25519-sign over canonical JSON
    │
    ├── IPFS pin via Hono /api/ipfs/pin
    │       │
    │       ├── Pin bij eigen Kubo-node
    │       ├── Pin bij provider A (extern)
    │       └── Pin bij provider B (extern)
    │
    ├── CID registreren in store-backend
    │
    └── Status: staged (wacht op auto-scan)

2.3 Pin-verificatie

3. Verified-fetch in Service Worker

3.1 Fetch-flow

SW ontvangt fetch-verzoek (CID)
    │
    ├── 1. Check Helia-lokaal (cache)
    │       │
    │       ├── Hit → hash-verificatie → return
    │       │
    │       └── Miss → ga naar stap 2
    │
    ├── 2. Gateway-allowlist check
    │       │
    │       ├── Eigen Kubo-node (preferentie)
    │       │
    │       └── Andere private trustless gateways
    │
    ├── 3. Fetch raw block of CAR
    │
    ├── 4. Hash-verificatie (bytes !== = reject)
    │
    ├── 5. Pin in Helia-lokaal (voor volgende keer)
    │
    └── 6. Return response

3.2 Verificatie-regels

3.3 Cache-strategie

TypeCache-duurReden
Immutable CIDOneindigCID = content hash. Na verificatie = permanent geldig.
Mutable pointer (IPNS)5 minutenKan wijzigen, frequente herverificatie.
Gateway responsePer Cache-Control headersRespecteer gateway-instellingen.

4. Geen publieke fallback (harde regel)

VEILIGHEIDSREGEL: MAOS gebruikt nooit publieke IPFS-gateways (ipfs.io, cloudflare-ipfs, enz.). Alleen private trustless gateways die door MAOS beheerd of goedgekeurd zijn. Als alle private gateways uitvallen: content niet beschikbaar, geen fallback.

4.1 Redenen

5. Gateway-allowlist beheer

VeldTypeBeschrijving
gatewaysstring[]Lijst van toegestane gateway-URLs
preferredstringPreferente gateway (eerste keuze)
timeoutnumberMaximale wachttijd per gateway (ms)
retryCountnumberAantal retries naar alternatieve gateways

6. Verwijzingen naar verwante specs

Volgende stap Na akkoord: Helia-integratie in SW + Kubo-cluster opzetten + pin-verificatie pipeline + gateway-allowlist in manifest-schema.

7. Grillvragen