Gateway Retrieval

GatewayRetrievalProvider reads encrypted bytes through an IPFS gateway and verifies the returned bytes against the expected CID before MeshKit decrypts anything.

Use it as a retrieval path or fallback, not as a substitute for authorization, metadata, or provider health.

Example

import { createMeshkit, GatewayRetrievalProvider, HttpIpfsProvider } from "@meshkit/core";

const storage = new HttpIpfsProvider({
  ipfsApiUrl: process.env.MESHKIT_IPFS_API!,
  metadataApiUrl: process.env.MESHKIT_METADATA_API!,
  token: process.env.MESHKIT_PROVIDER_TOKEN,
});

const mesh = await createMeshkit({
  provider: new GatewayRetrievalProvider({
    storage,
    gatewayUrl: "https://gateway.example",
    gatewayMode: "path",
  }),
});

const file = await mesh.files.put("gateway.txt", "verify after gateway read");
const verified = await mesh.retrieval.verifiedFetch(file.cid);

console.log(verified.proof.verified);

Gateway Modes

Match the gateway's documented behavior.

What Verification Does

expected CID
-> gateway fetch
-> recompute returned bytes
-> reject mismatch
-> decrypt only after verification and metadata checks

Gateway verification protects against wrong bytes. It does not prove the current identity is authorized. Authorization still depends on the encrypted envelope, identity, capsule, policy, vault, or capability requirements.

Production Caveats

• Gateways can cache stale or unavailable content.
• Gateway availability is not the same as Filecoin deal health.
• A gateway response does not replace MeshKit metadata.
• Authenticated gateways should use a token with retrieval-only scope where possible.
• Validate known fixtures with expected text or SHA-256 when operating a gateway.

Validation

MESHKIT_LIVE_GATEWAY=1 MESHKIT_GATEWAY_URL=https://gateway.example MESHKIT_GATEWAY_CID=bafk... npm run providers:gateway:live

Add MESHKIT_GATEWAY_EXPECTED_TEXT or MESHKIT_GATEWAY_EXPECTED_SHA256 when the validation fixture has known content.

Next Steps

• Proofs and CIDs
• Fallback provider
• Production setup