P2P Adapter

Direct device-to-device replication using libp2p with peer discovery, trust management, and NAT traversal.

Overview

The P2P adapter enables direct device-to-device replication without a central server. Built on libp2p, it handles peer discovery, connection management, and NAT traversal. Data flows directly between trusted devices over encrypted channels.

Setup

import { createStore } from "@cuitty/store/client";

const store = await createStore({
  module: "shared-notes",
  profile: {
    id: "p2p-notes",
    name: "P2P Notes",
    local: { adapter: "local.sqlite", path: ".cuitty/store/notes.sqlite" },
    remotes: [{
      id: "mesh",
      adapter: "p2p.libp2p",
      endpoint: "memory://notes",
    }],
    routes: [{ namespace: "notes", class: "record", localAdapter: "local.sqlite", remoteAdapters: ["mesh"] }],
    encryption: { atRest: "preferred", remote: "required", p2p: "required" },
    sync: { mode: "manual" },
  },
  schema: { notes: { class: "record" } },
});

The P2P adapter works alongside a local adapter (typically SQLite). Local storage handles reads and writes while P2P handles replication between devices.

Peer discovery

Store uses three discovery mechanisms:

1. mDNS — automatic discovery of peers on the same local network. No configuration needed.
2. Bootstrap peers — well-known peers that help new devices find each other.
3. DHT — distributed hash table for discovering peers across the internet.

const remote = {
  id: "mesh",
  adapter: "p2p.libp2p",
  endpoint: "memory://notes",
  path: ".cuitty/store/p2p",
};

Trust management

Not every discovered peer should be allowed to sync. Store uses a trust model where devices must be explicitly paired before data is exchanged.

Pairing and trust policy belong to the P2P runtime configuration and the application that owns device identity. Store records replicated operations after peers are authorized.

Once paired, devices exchange Ed25519 public keys. All subsequent sync payloads are signed and verified. Unpaired peers are rejected at the transport level.

Use the app/server peer endpoints to issue invites, revoke peers, and inspect trust state when running through the Cuitty Store app.

NAT traversal

Most devices sit behind NAT routers that block incoming connections. Store uses several techniques to establish connectivity:

• UPnP/NAT-PMP — automatic port mapping on supported routers
• Relay servers — traffic routes through a relay when direct connection fails
• Hole punching — coordinated connection attempts to traverse symmetric NATs

These mechanisms are enabled by default. No manual port forwarding is required for most networks.

Supported store classes

The P2P adapter supports records, events, and kv. Blob replication over P2P is not currently supported due to bandwidth constraints. Use the S3 adapter for blob storage with a sync server.