Storage-net-recovery: backup, audit en gateway
Besluiten vastgelegd: Q13 recovery optie B • Q14 audit-log met hash chain • OPFS-sync-beperkingen • IPFS private trustless gateways • status: ontwerp, nog geen code
Principe: Client-side encrypted VFS (OPFS + IDB) is de single source of truth. Server (Hono) bewaart alleen ciphertext blobs voor backup/sync. Herstel gebeurt via QR-recovery code. Elke VFS-operatie wordt geaudit met tamper-evident hash chain. IPFS-gegevens worden opgehaald via allowlisted private trustless gateways, nooit via publieke gateways.
1. Q13 — Herstel (optie B: encrypted ciphertext-only backup)
KEUZE: Backup bestaat uit een versleutelde ciphertext-blob op Hono + een QR-herstelcode voor de gebruiker. Nooit plaintext server-side. Geen Shamir guardians, geen no-recovery.
1.1 Architectuur
User device ──VFS snapshot──▶ encrypt met user-DEK ──▶ ciphertext blob ──▶ Hono /api/vault/backup
│
└── QR-recovery code = Enc(user-DEK, master-recovery-key) + metadata
User bewaart QR veilig (papier, password manager)
1.2 Flow bij herstel
| Stap | Actie | Waar |
| 1 | Gebruiker scant QR-code op nieuw apparaat | MAOS boot-flow |
| 2 | QR decodeert naar recovery-bundle: { encDEK, metadata, version } | Lokaal |
| 3 | Halo haalt ciphertext blob op via /api/vault/backup | Hono (ciphertext only) |
| 4 | Decrypt ciphertext met herstelde DEK | Lokaal (crypto.subtle) |
| 5 | VFS herstellen: IndexedDB + OPFS refill | Lokaal |
1.3 Beveiligingsregels
- Geen plaintext op server: Hono ziet alleen ciphertext + nonce. Zonder DEK = waardeloos.
- QR bevat geen key: QR-code is een encrypted bundle die alleen met het herstel-proces gedecodeerd kan worden.
- Geen Shamir: Geen secret-sharing, geen guardians, geen社会ische recovery. Eén QR = één herstelpad.
- Wipe bij herstel: Na succesvol herstel wordt de oude sessie op alle apparaten gewist (revoke alle tokens).
- Backup-frequency: Handmatig of bij significante wijzigingen (>10% van VFS-grootte). Geen automatische push naar server.
2. Q14 — Audit logging met hash chain
KEUZE: Elke VFS-write, grant, approval, en broadcast wordt gelogd met DApp-id + CID + wallet + hash. 90 dagen lokaal met tamper-evident hash chain. Alleen ciphertext summary naar Hono. User wipe alleen met step-up + 30-dagen abuse window.
2.1 Log-structuur
{
timestamp: number, // 10-digit Unix
type: "write" | "grant" | "revoke" | "approval" | "broadcast" | "deny",
dappId: string, // DApp identifier
cid: string, // IPFS CID (indien van toepassing)
wallet: string, // Wallet address (0x...)
method: string, // VAPI method (storage:write, wallet:send, etc.)
path: string, // VFS pad (indien van toepassing)
bytes: number, // Bytes geschreven (indien write)
hash: string, // SHA-256 van: prevHash + timestamp + type + dappId + ...
prevHash: string // Hash van vorige entry (hash chain)
}
2.2 Opslag en bewaarduur
| Locatie | Duur | Inhoud | Waarom |
| Lokaal (IndexedDB) | 90 dagen | Volledige audit logs + hash chain | Tamper-evident, snel opvraagbaar, geen server-afhankelijkheid |
| Hono (ciphertext summary) | 90 dagen | Gehashte samenvatting (geen paden, geen wallets) | Backup voor forensisch onderzoek, abuse-detectie |
| User wipe | 30 dagen abuse window | Lokaal gewist, summary blijft 30d op server | Voorkomt dat gebruiker logs wist na misbruik |
2.3 Hash chain verificatie
- Elke entry:
hash = SHA256(prevHash + timestamp + type + dappId + cid + wallet + method + path + bytes)
- Genesis: Eerste entry heeft
prevHash = "0"
- Verificatie: SharedWorker checkt hash chain bij elke nieuwe entry. Onderbreking = audit + blokkeer verdere operaties.
- Tamper-evident: Wijziging van één entry breekt de hele keten. Forensisch opvraagbaar.
2.4 Step-up bij wipe
- User wipe = step-up vereist: Gebruiker moet opnieuw authenticeren (wallet-signature) om logs te wissen.
- 30-dagen abuse window: Na wipe blijft de ciphertext summary 30 dagen op Hono voor onderzoek.
- Geen automatische wipe: Logs worden niet automatisch gewist. Gebruiker kiest bewust.
3. OPFS-sync-beperkingen (onderzoeksbevindingen)
ONDERZOEK: OPFS biedt synchronisatie-mogelijkheden maar heeft significante beperkingen die de architectuur beinvloeden.
3.1 Workers-only exclusive lock
- Regel: OPFS-synchronisatie (sync handles) is alleen beschikbaar in Web Workers, niet in de main thread.
- Gevolg: Alle VFS-operaties moeten via SharedWorker lopen. Geen directe OPFS-toegang vanuit iframe of main thread.
- Implementatie: SharedWorker houdt sync handles vast, voert alle reads/writes uit, geeft resultaten terug via postMessage.
3.2 Geen native rename
- Beperking: OPFS biedt geen native rename-operatie.
- Workaround: Copy + delete fallback. Atomair via: kopieer naar tijdelijk bestand, verwijder origineel, hernoem kopie.
- Risico: Niet volledig atomair bij crash. Backup via hash chain herstelt integriteit.
3.3 estimate() onbetrouwbaar
- Probleem:
navigator.storage.estimate() geeft onnauwkeurige waarden, vooral bij quota-wijzigingen.
- Oplossing: Handle
QuotaExceededError bij runtime. Probeer schrijven,vang fout, meld gebruiker.
- Geen voorafgaande check: Vertrouw niet op estimate() voor beslissingen. Schrijf eerst, check daarna.
3.4 IV-vereisten (AES-GCM)
| Parameter | Waarde | Waarom |
| IV grootte | 96-bit (12 bytes) | AES-GCM standaard, maximale efficiency |
| IV hergebruik | VERBODEN | Hergebruik met dezelfde key breekt beveiliging volledig |
| Tag grootte | 128-bit (16 bytes) | Volledige authenticiteit + integriteit |
| Chunking | Grote bestanden chunken | Voorkomt geheugenproblemen, maakt delen mogelijk |
3.5 Multi-tab BroadcastChannel advisory locks
- Advisory locks: OPFS-sync handles zijn exclusive per worker. Multi-tab toegang vereist coordinatie.
- BroadcastChannel: Tab-blad kan advisories sturen naar andere tabs via BroadcastChannel.
- Protocol: Tab A vraagt lock → Tab B checkt → geeft vrij of weigert → Tab A voert uit.
- Fallback: Na timeout (5s) wordt lock automatisch vrijgegeven (stale lock protection).
4. IPFS private trustless gateways (onderzoeksbevindingen)
ONDERZOEK: IPFS-gegevens worden opgehaald via allowlisted private trustless gateways. Geen publieke gateways, geen fallback naar onveilige bronnen.
4.1 Architectuur
SW fetch request ──▶ gateway-allowlist check ──▶ trusted private gateway ──▶ raw block/CAR response
│
└── onbekende gateway = deny + audit
4.2 Verplichtingen
- Alleen private trustless gateways: Geen publieke gateways (ipfs.io, cloudflare-ipfs, etc.). Alleen door MAOS beheerde of goedgekeurde gateways.
- Raw blocks/CAR: Haal IPFS-gegevens op als raw blocks of CAR-archieven, niet als HTTP-objecten.
- Geen public fallback: Als een private gateway niet bereikbaar is, probeer een andere private gateway. Nooit terugvallen op publieke bronnen.
- Allowlist in manifest: Elke DApp specificeert in haar manifest welke gateways gebruikt mogen worden.
4.3 Caching
| Type | Cache-duur | Reden |
| Immutable CID | Oneindig | CID = content hash. Als het eenmaal geverifieerd is, verandert het nooit. |
| Mutable pointers (IPNS) | 5 minuten | Kan wijzigen, frequente herverificatie vereist. |
| Gateway responses | Per headers | Respecteer Cache-Control van gateway. |
4.4 Pin-strategie
- 2-3 providers: Pin elke CID bij minimaal 2-3 betrouwbare pinning-providers.
- Eigen Kubo cluster: MAOS beheert een eigen Kubo-cluster voor kritieke inhoud (core, tier-0 systemen).
- Geen eenmansrisico: Als één provider uitvalt, blijven andere providers beschikbaar.
4.5 Ed25519 manifest-verificatie
- Canonical JSON: Manifesten worden geverifieerd op basis van canonical-JSON (gesorteerde keys, geen whitespace).
- Verificatie-timing: Bij pin-tijd (server-side) én vóór serve (client-side in SW).
- Geen ongeldige manifests: Ongeldige signature = geen pin, geen serve, audit-log.
5. Integratie met bestaande specs
| Spec | Koppeling |
| VFS-spec | Backup/sync van encrypted VFS. Audit-logging van VFS-operaties. |
| Wallet-spec | Wallet-adressen in audit logs. Step-up authenticatie bij wipe. |
| Container-spec | DApp-id en CID in audit logs. OPFS-toegang via SharedWorker. |
| Core-vs-IPFS | IPFS-pin-strategie. Gateway-allowlist in manifests. |
Volgende stap Na akkoord: implementatie van backup-flow (Q13) + audit-logging (Q14) + OPFS-sync in SharedWorker + gateway-allowlist in SW.