How to Implement Private Social Graph Storage on IPFS

A social graph is a map of relationships and interactions between users. In a decentralized context, storing this data privately is a core challenge. Traditional social platforms hold your graph on their servers, creating central points of failure and surveillance. Using IPFS (InterPlanetary File System) for storage provides censorship resistance and user data ownership, but its public-by-default nature requires a privacy layer. This guide explains how to combine IPFS with encryption to create a private, user-controlled social graph.

The architecture relies on separating the storage layer from the access control layer. User data—such as friend lists, follows, and private messages—is encrypted client-side before being pinned to IPFS via a service like Pinata or web3.storage. The resulting Content Identifier (CID) is just an immutable hash of the encrypted data; the plaintext content remains hidden. Access is managed through decentralized identifiers (DIDs) and key exchange protocols, ensuring only authorized users can decrypt specific CIDs.

For implementation, you can use libraries like js-ipfs or Helia for IPFS operations and libp2p for peer-to-peer networking. Encryption is typically handled with AES-GCM for symmetric encryption of the data payload. The encryption key is then asymmetrically encrypted for each authorized recipient using their public key, a pattern known as hybrid encryption. These encrypted keys, along with the data CID and access rules, can be stored in a Ceramic stream or a smart contract on a blockchain like Ethereum or Polygon to serve as the permissioned index.

Consider a simple follow relationship: User A encrypts a JSON object {"follows": "UserB_DID"} and pins it to IPFS, receiving CID QmExample. User A then creates a W3C Verifiable Credential granting User B permission to read that CID, signing it with their DID. This credential is sent to User B via a secure channel. User B's client fetches the encrypted data from IPFS using the CID, verifies the credential, and uses their private key to decrypt the access key, finally decrypting the social graph data. Frameworks like @veramo/core can manage these DID and credential workflows.

This approach has significant implications. It enables portable social graphs where users can move their connections between applications. It also facilitates selective disclosure, where a user can prove a specific relationship (e.g., "I follow this DAO") without revealing their entire graph. However, developers must carefully manage key storage and revocation, and consider metadata privacy, as patterns of CID updates and network requests can still leak information. Using IPFS Private Networks or IPFS over Libp2p Circuit Relay with encryption can help mitigate some network-level risks.

To start building, fork a template like the ipfs-private-social-graph demo repository which integrates IPFS, Ceramic, and key-did-provider-ed25519. The core workflow involves: 1) Generating a DID for the user, 2) Encrypting social data with a random key, 3) Pinning the ciphertext to IPFS, 4) Writing the access grant to a mutable data store, and 5) Building a resolver that fetches and decrypts data for authorized requests. This model forms the foundation for the next generation of decentralized social networks (DeSo).

To build a private social graph on IPFS, you'll need a development environment with Node.js (v18 or later) and npm or yarn installed. The core of your application will interact with the InterPlanetary File System (IPFS) via its programmatic APIs. You can choose between running a local IPFS node using js-ipfs or go-ipfs, or connecting to a remote node via a service like Infura or Pinata. For managing private data, familiarity with public-key cryptography and symmetric encryption is crucial, as raw data should never be stored in plaintext on the decentralized network.

Key libraries to install include ipfs-core for Node.js IPFS operations and libp2p for peer-to-peer networking. For encryption, you'll use a library like libsodium-wrappers or the Web Crypto API. Your social graph data structure—representing users, connections, and interactions—will be serialized, likely using Protocol Buffers or CBOR for efficiency, before being encrypted and stored. Understanding Content Identifiers (CIDs) is essential; they are the immutable hashes that point to your data on IPFS and will be the primary handles for retrieving graph fragments.

A critical prerequisite is designing your data schema and access control model. Will you use attribute-based encryption (ABE), proxy re-encryption, or simple key-sharing? Tools like Ceramic Network or OrbitDB can provide higher-level abstractions for mutable, permissioned data on IPFS, which may simplify parts of the implementation. Ensure you have a method for key management, such as using MetaMask for Ethereum-based key derivation or a dedicated secret management service, as losing encryption keys means permanently losing access to the private data.

A private social graph on IPFS stores user connections—follows, friends, interactions—as encrypted data on the decentralized network. The core challenge is ensuring data availability via IPFS's content-addressed storage while maintaining privacy through client-side encryption. Unlike centralized databases, you don't store raw relationship data. Instead, you store encrypted social graph objects (ESGOs) as IPFS Content Identifiers (CIDs). Each user's graph is a collection of these CIDs, with the decryption keys controlled solely by the user or shared via secure protocols. This model separates storage from access, leveraging IPFS for resilient, permanent storage of the ciphertext.

The data model typically revolves around a directed graph structure. A user's social graph can be represented as a set of edges, where each edge is a JSON object containing metadata like follower, followee, timestamp, and type. For example: {"from": "userA", "to": "userB", "createdAt": 1234567890, "edgeType": "follow"}. This object is then serialized, encrypted, and published to IPFS, returning a CID. The user's local index, which can be stored in a decentralized identity wallet or a private database, maps to these CIDs, allowing them to reconstruct their graph by fetching and decrypting the ESGOs.

Encryption is paramount for privacy. Use symmetric encryption (like AES-GCM) with a unique key for each social graph update or batch of edges. The encryption key itself must be managed securely; it can be derived from the user's master key or generated per session. To enable selective sharing—allowing a dApp to read your graph—you implement key encapsulation. Share the symmetric key by encrypting it with the recipient's public key (using ECIES or similar). The encrypted social graph CID and the encapsulated key can then be stored together in a shareable package, still on IPFS.

Implementing this requires a clear workflow. 1. Graph Update: A user creates a new connection edge locally. 2. Encryption: The edge data is encrypted with a fresh symmetric key. 3. Storage: The resulting ciphertext is added to IPFS (using ipfs.add()), yielding a CID. 4. Indexing: The user's local client stores a mapping from the edge identifier to the CID and the encryption key (secured in a keystore). 5. Retrieval & Sharing: To view the graph, the client fetches CIDs from IPFS, decrypts them with the stored keys, and renders the data. Sharing involves creating and publishing the key encapsulation package.

Tools like IPFS Kubo, Helia, or web3.storage handle the IPFS interaction. For encryption, use robust libraries such as libsodium or Web Crypto API. A critical architectural consideration is key management. Losing the encryption keys means losing access to the graph data permanently, as IPFS only stores the unreadable ciphertext. Therefore, integrate with secure key recovery systems, often tied to the user's decentralized identifier (DID) and mnemonic phrase. This architecture ensures user sovereignty: the social graph is portable, censorship-resistant, and private, with access governed by cryptography rather than a central server's permissions.

A Decentralized Identifier (DID) is a W3C standard for a new type of verifiable, self-sovereign identifier. Unlike an email address or social media handle, a DID is not issued or controlled by any company. It is a URI, like did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK, that points to a DID Document. This document, which you will store on IPFS, contains the public keys, service endpoints, and other metadata needed to interact with your identity in a decentralized network. The did:key method is a simple, widely supported format ideal for this use case.

To create a DID, you first generate a cryptographic key pair. The private key is kept secret and used for signing data, while the public key becomes part of the DID's identifier. Using a library like @digitalbazaar/did-method-key in Node.js, you can generate a DID in a few lines of code. The resulting DID Document is a JSON-LD object that specifies the public key for verification and can list service endpoints—such as the IPFS CID where your encrypted social graph data will be stored.

The power of a DID lies in its verifiability. When you sign a piece of data (like a new social connection) with your private key, anyone can use the public key in your publicly accessible DID Document to verify the signature's authenticity. This creates a cryptographically secure link between your identity and your actions, forming the basis of trust in a decentralized system. Your DID is your portable, permanent identity anchor across applications.

For a private social graph, your DID Document should include a service endpoint pointing to your encrypted data store. This is done by adding a service array to the document. For example, a service entry with type EncryptedSocialGraphStore and a serviceEndpoint of ipfs://bafy... tells applications where to find your data. You will host this lightweight DID Document on IPFS, and its Content Identifier (CID) becomes the immutable reference for your identity's current state.

Before proceeding, ensure you have a Node.js environment set up. Install the necessary package: npm install @digitalbazaar/did-method-key. The following code snippet demonstrates generating a did:key and its initial document. Remember, safeguarding the generated private key material is critical, as it represents control over your decentralized identity.

A social graph is fundamentally a set of directed edges connecting user identifiers. For a decentralized application, each edge should be a self-contained, immutable data object. A standard structure includes the from (follower/actor), to (followee/target), a timestamp, and a type (e.g., "follow", "block"). This data is serialized into a deterministic format like JSON or CBOR before hashing. The resulting Content Identifier (CID) serves as the unique, content-addressed pointer for this edge on IPFS, ensuring data integrity.

To make these edges private, you must encrypt the relationship data before publishing it to IPFS. Use a symmetric encryption algorithm like AES-GCM, which provides both confidentiality and integrity. The encryption key should be derived from a secret shared exclusively between the two users involved in the edge. A common method is using Elliptic Curve Diffie-Hellman (ECDH) key exchange: each user's public key is known, allowing them to independently compute the same shared secret without transmitting it.

Implementing this requires a client-side library. Using libp2p's crypto utilities in JavaScript, you can generate a shared key and encrypt the edge object. The encrypted payload, or ciphertext, is what gets stored on IPFS. Crucially, the plaintext metadata needed to find this edge—such as the public keys of the involved parties or a public label—must be stored separately, often in a user's public profile or a dedicated index, to enable discovery without revealing the relationship's nature.

Consider a follow action from Alice (public key alice-pk) to Bob (public key bob-pk). Your code would: 1) Serialize the {from: alice-pk, to: bob-pk, type: 'follow', timestamp: 12345} edge. 2) Use ECDH with alice-pk and bob-pk to derive a shared secret. 3) Encrypt the serialized edge with AES-GCM using this secret. 4) Add the resulting ciphertext to IPFS, receiving a CID like bafybei.... Only Alice and Bob can decrypt this CID to view the relationship.

This model creates a disconnected graph where edges are private blobs scattered across IPFS. To reconstruct a user's social circle, their client must fetch and decrypt all edges where they are a participant. This design shifts the computational burden of graph traversal to the client, preserving privacy by ensuring no central service ever has access to the complete, unencrypted social graph. The public IPFS network only ever sees opaque, encrypted data.

Pinning is the mechanism that tells IPFS to keep your data stored and accessible. When you add a file to IPFS, you receive a unique Content Identifier (CID). Without pinning, the data is considered temporary and may be garbage-collected by your local IPFS node or by remote nodes that haven't explicitly requested to keep it. For a private social graph, where data persistence is critical, you must explicitly pin the encrypted data's CID to guarantee its permanence on the network.

You can pin data using the command line, the IPFS HTTP API, or programmatically with libraries like js-ipfs or ipfs-http-client. The core operation is straightforward: ipfs pin add <CID>. However, for production applications, you should consider using a pinning service like Pinata, nft.storage, or web3.storage. These services run dedicated IPFS nodes that guarantee your data's availability, offering redundancy and reliability beyond a single local node. They provide APIs for programmatic pinning, which integrates seamlessly into your application's backend workflow.

When implementing pinning in your application, the workflow typically follows these steps: 1) Encrypt the structured social graph data (e.g., a JSON file). 2) Add the encrypted data buffer to your IPFS node or service, receiving a CID. 3) Immediately pin that CID. Here's a simplified example using the ipfs-http-client library in Node.js:

javascriptCopy
const { create } = require('ipfs-http-client');
const ipfs = create({ url: 'https://ipfs.infura.io:5001' });

async function pinEncryptedData(encryptedBuffer) {
  const { cid } = await ipfs.add(encryptedBuffer);
  await ipfs.pin.add(cid);
  console.log(`Pinned encrypted social graph with CID: ${cid}`);
  return cid.toString();
}

This CID is the final, persistent reference you will store in your smart contract or backend database.

For enhanced data resilience, implement redundant pinning. This involves pinning the same CID across multiple independent pinning services or a consortium of your own nodes. This strategy mitigates the risk of a single point of failure. Furthermore, monitor the health of your pins. Most pinning services offer APIs to check pin status. You should set up periodic checks to ensure your crucial social graph data remains pinned and accessible, triggering alerts or re-pinning operations if a service fails.

Remember, the CID is immutable. Any change to the underlying encrypted data—even a single byte—will generate a completely different CID, which must be pinned anew. Your application logic must handle this by updating the stored CID reference whenever the user's social graph is modified. The combination of client-side encryption and decentralized, pinned storage on IPFS creates a robust foundation for user-owned social data, aligning with Web3 principles of sovereignty and resilience.

A queryable index is the bridge between your application's logic and the decentralized storage layer. It answers the question: "Where is User A's latest profile data stored?" The core component is a key-value store where the key is a public identifier (like a user's wallet address or a did:key) and the value is the IPFS Content Identifier (CID) pointing to the user's encrypted data blob. This index must be stored in a mutable, queryable location, which is why it's typically hosted on a decentralized database like Ceramic, Tableland, or OrbitDB, or even a permissioned smart contract on an L2 like Arbitrum or Optimism.

The index entry should be structured to handle data versioning and access control. A robust schema includes fields for the data cid, a timestamp of the last update, the encryptionPublicKey used for the data (if using asymmetric encryption), and a dataType label (e.g., profile, posts, connections). This allows your application to fetch the latest CID for a specific user and data type. When a user updates their information, your app creates a new encrypted IPFS blob, gets the new CID, and publishes a transaction to update the index entry, making the old CID obsolete.

Implementing this requires writing to your chosen indexing platform. For example, using Ceramic's ComposeDB, you would define a GraphQL data model for your index. A user's client would then use their DID (Decentralized Identifier) to authenticate and mutate their own index record. Here's a simplified conceptual flow in code:

javascriptCopy
// 1. User encrypts & uploads new profile data to IPFS
const encryptedData = await encrypt(profileData, symmetricKey);
const cid = await ipfsClient.add(encryptedData);

// 2. User updates their index on Ceramic/ComposeDB
const mutation = `mutation {
  setProfileIndex(input: {
    content: {
      ownerDID: "${userDID}",
      latestProfileCID: "${cid}",
      timestamp: "${new Date().toISOString()}"
    }
  }) {
    document {
      id
      latestProfileCID
    }
  }
}`;
// Execute the GraphQL mutation

For applications requiring complex queries—like "find all users who listed 'Web3' as an interest"—a simple key-value index is insufficient. This requires secondary indexing. One pattern is to create separate, topic-specific index streams. For instance, when a user updates their profile with interests, the client could also write an entry to a shared interest:Web3 index stream, containing only their DID and the CID of their public profile summary (not private data). Ceramic's deterministic stream IDs or Tableland's SQL WHERE clauses are designed for this relational query pattern, enabling social discovery without central servers.

Finally, consider index privacy. While the CIDs in the index point to encrypted data, the act of updating an index entry is a public transaction. To obfuscate social graph activity, you can implement techniques like delayed publishing (batching index updates) or using zero-knowledge proofs to validate data updates without revealing the user's DID in the public index. The chosen strategy depends on your application's specific privacy and performance requirements, balancing decentralization with user experience.

A consent-based query system is the gateway between your application and the private user data stored on IPFS. Its primary function is to authenticate requests, verify permissions against the user's consent registry (like a smart contract), and only then fetch and decrypt the authorized data. This architecture ensures that data access is never automatic; every query requires explicit, verifiable user approval. Think of it as the bouncer for your decentralized data vault, checking credentials at the door.

The core of this system is a serverless function or a dedicated API service. When your dApp needs social data—for example, a user's connections to display a "Friends using this app" feature—it sends a signed request to this query endpoint. The request must include the requester's address, the target user's identifier (e.g., their DID), and a proof of consent, such as a signature or a valid ERC-4361 Sign-In with Ethereum message. The service validates this proof against the on-chain consent registry to confirm the user has granted this specific application access.

Upon successful validation, the query service retrieves the encrypted data. It first fetches the Content Identifier (CID) pointer from the user's public profile or a dedicated index. Using the Lit Protocol or a similar decentralized access control network, the service provides the necessary cryptographic signatures or key shares to decrypt the data. Only after this step is the plaintext social graph data—formatted as JSON-LD or a similar structured format—returned to the requesting application. All decryption happens server-side within the secure enclave of the service, never exposing private keys to the client.

Implementing this requires careful error handling. Your query service must gracefully handle scenarios like revoked consent (the registry entry is removed), expired permissions, or attempts to access non-existent CIDs. Logging these events (without logging private data) is crucial for security audits. Furthermore, consider implementing rate limiting and query cost mechanisms to prevent abuse, as each decryption operation on networks like Lit has an associated gas cost.

Here is a simplified Node.js pseudocode example for a query endpoint using Express.js and the Lit Protocol SDK:

javascriptCopy
app.post('/query/graph', async (req, res) => {
  const { requester, targetUserDid, consentProof } = req.body;
  // 1. Verify on-chain consent
  const hasConsent = await consentRegistry.checkAccess(requester, targetUserDid, consentProof);
  if (!hasConsent) return res.status(403).send('Access denied');

  // 2. Fetch encrypted CID from public profile
  const userProfile = await ipfs.get(targetUserDid + '/profile.json');
  const encryptedSymmetricKey = userProfile.encryptedKey;
  const encryptedDataCid = userProfile.graphCid;

  // 3. Decrypt using Lit Protocol
  const decryptedKey = await lit.decrypt(encryptedSymmetricKey);
  const encryptedData = await ipfs.get(encryptedDataCid);
  const socialGraph = await decryptData(encryptedData, decryptedKey);

  // 4. Return authorized data subset
  res.json({ graph: socialGraph.connections });
});

Finally, design your query responses to follow the principle of least privilege. Even with general consent, the API should only return the specific data fields needed for the function (e.g., only public keys and usernames, not private messages). This granularity can be encoded in the consent token itself. By building this robust, permissioned query layer, you create a user-trusted application that leverages the social graph's power without compromising the privacy guarantees of your decentralized storage system.