Pinning and IPFS Cluster

Every object zev stores is content-addressed, so it's already a real IPFS object - but content on a single node's local disk is one hardware failure away from gone. Pinning is how zev makes sure content actually stays available, and IPFS Cluster is what coordinates that pinning across more than one node. ## Pinning Pinning uploads content to IPFS and marks it as protected from garbage collection. The result is a standards-compliant CID that resolves on any IPFS gateway or node - it isn't a zev-specific identifier. ```bash curl -X POST "https://your-server/v1/pins?name=my-file" \ --data-binary @my-file \ -H "Authorization: Bearer <pat>" ``` The response includes a signed attestation - a message and signature proving the server pinned that exact CID, at that exact size, at that exact time - which anyone can verify later without trusting the server's word for it: ```bash curl "https://your-server/v1/pins/<cid>/verify" ``` Pinning respects per-user storage quotas and pin-count limits, scaled by account tier, and checks both before accepting new content. ## IPFS Cluster A single IPFS node pinning content is still a single point of failure. IPFS Cluster coordinates pinning across a set of IPFS peers, so the same content can be replicated to more than one of them, with cluster-wide status tracking for whether each peer has actually finished pinning it. zev's pinning API talks to the cluster's own `/add` endpoint, which adds content to IPFS and pins it across the cluster in one atomic step - rather than adding to a single node and pinning separately, which leaves a gap where the content exists but isn't yet tracked for replication. ### Replication factor Every pin carries a replication factor: how many cluster peers should hold a copy. Free-tier pins use a fixed replication factor of 1. Premium-tier pins use `-1`, which means "pin to every available peer" rather than a fixed count - deliberately, since a fixed minimum larger than the cluster's actual peer count causes the pin to fail. `-1` adapts to however many peers exist, so premium replication automatically becomes real multi-peer redundancy the moment more peers join the cluster, with no code or configuration change needed on zev's side. ### Checking status Two endpoints expose real cluster state, not simulated or cached data: ```bash curl "https://your-server/v1/pins/<cid>/cluster-status" # {"cid":"...","status":"pinned","pinned_peers":1,"total_peers":1} curl "https://your-server/v1/cluster/health" # {"cluster_id":"...","peername":"...","peer_count":1,"total_freespace_bytes":9811005992} ``` `cluster-status` reports per-pin replication health: how many of the cluster's peers have confirmed the pin as `"pinned"`, versus still `"pinning"` or in an `"error"` state. `cluster/health` reports the cluster as a whole - current peer count and total free space across all of them, queried live from the cluster on every call. ## Why this design Pinning and cluster coordination are kept as two distinct steps precisely so replication can grow without anything else changing. A single-peer deployment and a ten-peer deployment run the exact same pinning code; the only difference is how many peers show up in `cluster-status` and `cluster/health`, and how far `-1` replication actually reaches. Nothing about the pinning API, the attestation scheme, or the quota system needs to know how many peers exist.