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)
- Rol: Lokaal IPFS-knooppunt voor directe toegang tot pinned content. Zero-network bij cache-hit.
- Implementatie: Helia (JavaScript IPFS-impl). Draait in Service Worker context.
- Storage: IndexedDB voor blocks + metadata. Geen OPFS (SW-beperkingen).
- Cache-strategie: Immutable CIDs = oneindig. Mutable pointers (IPNS) = 5 min TTL.
- Integratie: SW roept
helia.get(CID) aan. Bij hit = direct. Bij miss = gateway-fetch +本地 pin.
1.3 Eigen Kubo-cluster
| Component | Locatie | Rol |
| Kubo-node (primary) | Hono-server | Volledige IPFS-node voor pin + serve |
| Kubo-node (replica) | Backup-server | Replicatie van kritieke CIDs (core, tier-0) |
| Helia (client) | Service Worker | Lokale cache + directe toegang |
2. Pin-strategie (multi-provider)
2.1 Pin-regels per tier
| Tier | Aantal providers | Providers | Verplicht |
| Tier-0 (core) | 3+ | Eigen Kubo + 2 externe pinning-services | Ja, altijd |
| Tier-1 (verified) | 2+ | Eigen Kubo + 1 externe pinning-service | Ja |
| Tier-2 (third-party) | 1+ | Minimaal 1 pinning-service | Ja (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
- Elke 24 uur: Controleer of alle pinned CIDs nog beschikbaar zijn bij alle providers.
- Bij falen: Provider uit allowlist + herpin bij alternatieve provider.
- Geen eenmansrisico: Als één provider uitvalt, blijven andere beschikbaar.
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
- Hash-match: Bij elke fetch wordt de hash van de ontvangen data geverifieerd tegen de CID. Mismatch = reject + audit.
- Geen publieke gateways: Alleen private trustless gateways in allowlist. Geen ipfs.io, cloudflare-ipfs, enz.
- Geen fallback: Als private gateway niet bereikbaar is, probeer andere private gateway. Nooit terugvallen op publieke bronnen.
- CAR vs raw blocks: Bij voorkeur CAR-archieven voor batch-ophaling. Raw blocks voor enkele items.
3.3 Cache-strategie
| Type | Cache-duur | Reden |
| Immutable CID | Oneindig | CID = content hash. Na verificatie = permanent geldig. |
| Mutable pointer (IPNS) | 5 minuten | Kan wijzigen, frequente herverificatie. |
| Gateway response | Per Cache-Control headers | Respecteer 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
- Integriteit: Publieke gateways kunnen content manipuleren of censureren.
- Privacy: Publieke gateways loggen requests, kunnen gebruikersgedrag volgen.
- Betrouwbaarheid: Publieke gateways kunnen zonder waarschuwing uitvallen of veranderen.
- Controle: Eigen gateways = volledige controle over beschikbaarheid en prestaties.
5. Gateway-allowlist beheer
| Veld | Type | Beschrijving |
gateways | string[] | Lijst van toegestane gateway-URLs |
preferred | string | Preferente gateway (eerste keuze) |
timeout | number | Maximale wachttijd per gateway (ms) |
retryCount | number | Aantal 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
- Vraag 1: Moet de Helia-cache ook CIDs van tier-2 DApps cachen, of alleen tier-0/tier-1? Bij large-scale (10k DApps) kan dit geheugenproblemen veroorzaken.
- Vraag 2: Hoe wordt de gateway-allowlist gesynchroniseerd tussen Kubo-nodes: via een signed config, of via IPNS-self-pinning?
- Vraag 3: Wat is het gedrag als een pinned CID niet meer beschikbaar is bij een provider: direct herpin bij alternatieve provider, of wachten op dagelijkse verificatie?