IPFS HTTP And Kubo

HttpIpfsProvider writes encrypted MeshKit envelopes through a Kubo-compatible IPFS HTTP API and uses a MeshKit metadata endpoint for proofs, capsules, mailboxes, sync jobs, logs, and health checks.

A stock Kubo daemon is only the byte-storage side of this provider. It does not serve MeshKit routes such as proofs, capsules, vaults, capabilities, or mailboxes. Production deployments need a MeshKit-compatible metadata service alongside the Kubo API.

Config

{
  "version": 1,
  "appId": "mk_kubo_rpc",
  "provider": {
    "type": "ipfs-http",
    "ipfsApiUrl": "https://ipfs-api.internal.example",
    "metadataApiUrl": "https://meshkit-metadata.internal.example",
    "tokenEnv": "MESHKIT_PROVIDER_TOKEN",
    "timeoutMs": 15000,
    "retries": 2
  }
}

Application code can construct the provider directly:

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

const provider = new HttpIpfsProvider({
  ipfsApiUrl: process.env.MESHKIT_IPFS_API!,
  metadataApiUrl: process.env.MESHKIT_METADATA_API!,
  token: process.env.MESHKIT_PROVIDER_TOKEN,
  timeoutMs: 15_000,
  retries: 2,
});

const mesh = await createMeshkit({ provider, identity: "server" });
const report = await mesh.doctor.run();

console.log(report.ok);

Kubo Versus MeshKit Metadata

Endpoint	Role
`ipfsApiUrl`	Kubo-compatible RPC for encrypted bytes, such as block writes and reads
`metadataApiUrl`	MeshKit API for proofs, capsules, mailboxes, sync jobs, vaults, capabilities, logs, and health

Do not point metadataApiUrl at a stock Kubo daemon and expect MeshKit metadata routes to exist.

Kubo, Cluster Proxy, And Cluster REST

A Kubo-compatible IPFS HTTP API can be a stock Kubo daemon or an IPFS Cluster IPFS Proxy endpoint when the operator intentionally exposes Kubo-compatible paths.

HttpIpfsClusterProvider is different. It targets the private Cluster REST contract, not Kubo /api/v0. If the endpoint is an IPFS Proxy, configure it as ipfsApiUrl on HttpIpfsProvider.

Validation

npx -p @meshkit/cli meshkit providers test --json

Repository live validation for a local daemon:

MESHKIT_LIVE_IPFS=1 MESHKIT_IPFS_API=http://127.0.0.1:5001 npm run providers:ipfs:live

Use the negative metadata harness when you need evidence that a stock Kubo endpoint is not pretending to be a MeshKit metadata service:

MESHKIT_LIVE_KUBO_METADATA=1 MESHKIT_KUBO_METADATA_BASE_URL=http://127.0.0.1:5001 npm run providers:kubo-metadata-negative:live

Production Caveats

Do not expose unrestricted Kubo RPC directly to browsers or public mobile clients.
Put Kubo behind TLS, authentication, network policy, rate limits, and an operator-owned service boundary.
Keep Kubo repo lifecycle, pin policy, garbage collection, and peering under operator control.
Validate write, read, proof, capsule, and cleanup behavior before production.
Use separate tokens for storage and metadata if they have different blast radius.