{"id":32296351,"url":"https://github.com/jxoesneon/ipfs","last_synced_at":"2026-05-16T14:01:51.903Z","repository":{"id":258774785,"uuid":"875454627","full_name":"jxoesneon/IPFS","owner":"jxoesneon","description":"Production-ready IPFS implementation in Dart with full protocol support, P2P networking, Gateway mode, and offline capabilities. Supports mobile (Flutter) and web platforms.","archived":false,"fork":false,"pushed_at":"2026-05-14T19:47:24.000Z","size":86616,"stargazers_count":10,"open_issues_count":3,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-05-14T20:30:14.145Z","etag":null,"topics":["bitswap","content-addressable","dart","decentralized","dht","distributed-systems","flutter","github-sponsors","ipfs","libp2p","p2p"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/dart_ipfs","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jxoesneon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"jxoesneon","ko_fi":"jxoesneon"}},"created_at":"2024-10-20T02:53:33.000Z","updated_at":"2026-05-14T19:45:52.000Z","dependencies_parsed_at":"2024-10-23T05:11:34.543Z","dependency_job_id":"28d7eae7-6aa3-48ad-a089-f3179402737a","html_url":"https://github.com/jxoesneon/IPFS","commit_stats":null,"previous_names":["jxoesneon/ipfs"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/jxoesneon/IPFS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxoesneon%2FIPFS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxoesneon%2FIPFS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxoesneon%2FIPFS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxoesneon%2FIPFS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jxoesneon","download_url":"https://codeload.github.com/jxoesneon/IPFS/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxoesneon%2FIPFS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33105712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitswap","content-addressable","dart","decentralized","dht","distributed-systems","flutter","github-sponsors","ipfs","libp2p","p2p"],"created_at":"2025-10-23T04:02:28.084Z","updated_at":"2026-05-16T14:01:51.896Z","avatar_url":"https://github.com/jxoesneon.png","language":"Dart","funding_links":["https://github.com/sponsors/jxoesneon","https://ko-fi.com/jxoesneon"],"categories":[],"sub_categories":[],"readme":"# dart_ipfs\n\nA complete, production-ready IPFS (InterPlanetary File System) implementation in Dart, supporting offline, gateway, and full P2P modes. Built for a seamless multi-platform experience.\n\n[![pub package](https://img.shields.io/pub/v/dart_ipfs.svg)](https://pub.dev/packages/dart_ipfs)\n[![Dart](https://img.shields.io/badge/dart-%3E%3D3.0.0-blue.svg)](https://dart.dev/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003e **TL;DR**: A pure-Dart IPFS node supporting Dart VM (Windows, macOS, Linux) and Web (Chrome, Firefox, Safari). The `IpfsPlatform` abstraction automatically handles storage (File System vs. IndexedDB) and networking based on the target platform.\n\n---\n\n## 🌍 Multi-Platform Support\n\n| Platform | Runtime | Storage | Networking |\n|----------|---------|---------|------------|\n| **Windows** | Dart VM | File System | TCP / UDP / QUIC |\n| **macOS** | Dart VM | File System | TCP / UDP / QUIC |\n| **Linux** | Dart VM | File System | TCP / UDP / QUIC |\n| **Web** | JS / Wasm | IndexedDB | WebSocket / WebRTC |\n\n---\n\n## 📚 Documentation\n\n- **[Architecture Guide](doc/ARCHITECTURE.md)** — Deep dive into the Manager-Handler pattern\n- **[Wiki](https://github.com/jxoesneon/IPFS/wiki)** — Guides, Installation, Architecture\n- **[API Reference](https://jxoesneon.github.io/IPFS/)** — Auto-generated Dart docs\n\n---\n\n## Table of Contents\n\n- [What's New in v1.10](#-whats-new-in-v110)\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Use Cases](#use-cases)\n- [Architecture](#architecture)\n- [Security](#-security)\n- [Performance](#performance)\n- [Troubleshooting](#troubleshooting)\n- [Examples](#examples)\n- [Contributing](#contributing)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n---\n\n## 🚀 What's New in v1.10\n\n### Major Features\n\n| Feature                 | Description                                                  |\n| ----------------------- | ------------------------------------------------------------ |\n| **IpfsPlatform**        | Unified abstraction shielding core logic from platform differences. |\n| **IndexedDB Storage**   | Production-ready persistent storage for Web browsers.         |\n| **SecurityManager**     | Multi-platform encrypted keystore for secure identity management.|\n| **Standardization**     | 100% compliance with Kubo (go-ipfs) protocol standards.       |\n| **Browser Testing**     | Full CI/CD integration for Chrome and Firefox.                |\n\n---\n\n## Features\n\n### ✅ Core IPFS Functionality\n\n- **Content-Addressable Storage**: CID v0 and v1 support\n- **UnixFS**: Full file system implementation with chunking\n- **DAG-PB**: MerkleDAG operations and IPLD traversal\n- **CAR Files**: Import/export support\n- **Pinning**: Content persistence management\n\n### ✅ Networking \u0026 NAT Traversal\n\n- **Bitswap 1.2.0**: Efficient block exchange with wantlist management\n- **Kademlia DHT**: Distributed hash table for peer/content routing\n- **AutoNAT**: Automatic NAT type detection\n  - Direct connectivity testing\n  - Symmetric NAT detection\n  - Periodic dialback verification\n- **UPnP/NAT-PMP**: Automatic port mapping via `NatTraversalService`\n- **Circuit Relay v2**: Hole-punching via relay peers\n  - HOP protocol (relay serving)\n  - STOP protocol (connection handling)\n  - RESERVE protocol (relay reservations)\n- **libp2p Core**: Native TCP/Noise transport for standard P2P networking\n- **PubSub**: Real-time messaging (Gossipsub)\n- **mDNS**: Local peer discovery\n- **Bootstrap Peers**: Network connectivity initialization\n\n### ✅ Services\n\n- **HTTP Gateway**: Read-only and writable modes\n- **RPC API**: Compatible with go-ipfs API\n- **IPNS**: Mutable naming system with Ed25519 signatures\n- **DNSLink**: Domain-based content resolution\n- **GraphSync**: Efficient graph synchronization protocol\n- **Metrics**: Prometheus-compatible monitoring\n\n### ✅ Security\n\n- **Production Cryptography**\n  - secp256k1 key exchange (128-bit security)\n  - ChaCha20-Poly1305 AEAD encryption\n  - SHA-256 content hashing\n  - Ed25519 IPNS signatures\n- **Encrypted Keystore (SEC-008)**\n  - AES-256-GCM encryption\n  - PBKDF2 key derivation\n  - Automatic key rotation\n  - Memory zeroing on lock\n- **Sybil Protection (SEC-005)**\n  - S/Kademlia Proof-of-Work for PeerId verification\n  - Configurable difficulty via `SecurityConfig.dhtDifficulty`\n- **Rate Limiting**\n  - Per-client authentication throttling\n  - DHT provider announcement limits\n- **Content Verification**\n  - Automatic CID validation\n  - Merkle tree verification\n  - Block integrity checks\n\n### ✅ Web Platform\n\n- **`IPFSWebNode`**: Browser-compatible implementation\n- **IndexedDB Storage**: Persistent local storage\n- **WebSocket Transport**: Networking via secure relays\n- **Bitswap \u0026 PubSub**: Full protocol support in browsers\n\n---\n\n## Quick Start\n\n### Installation\n\nAdd to your `pubspec.yaml`:\n\n```yaml\ndependencies:\n  dart_ipfs: ^1.10.0\n```\n\nOr from Git for latest development:\n\n```yaml\ndependencies:\n  dart_ipfs:\n    git:\n      url: https://github.com/jxoesneon/IPFS.git\n```\n\nThen run:\n\n```bash\ndart pub get\n```\n\n### Windows Setup\n\n**Important**: On Windows, P2P networking requires `libsodium` for cryptography.\n\n**✅ Automatic Setup**: dart_ipfs automatically detects and installs libsodium via `winget` on first run.\n\n**Manual Installation** (if auto-install fails):\n\n```powershell\n# Via winget (recommended)\nwinget install jedisct1.libsodium\n\n# Or use offline mode (no P2P)\nIPFSConfig(offline: true)\n```\n\n### Basic Usage\n\n#### Offline Mode (Local Storage)\n\n```dart\nimport 'package:dart_ipfs/dart_ipfs.dart';\n\nvoid main() async {\n  final node = await IPFSNode.create(\n    IPFSConfig(\n      dataDir: './ipfs_data',\n      offline: true,  // No P2P networking\n    ),\n  );\n\n  await node.start();\n\n  // Add content\n  final cid = await node.add('Hello, IPFS!');\n  print('Added with CID: $cid');\n\n  // Retrieve content\n  final retrieved = await node.cat(cid);\n  print('Retrieved: $retrieved');\n\n  await node.stop();\n}\n```\n\n#### Gateway Mode (HTTP Server)\n\n```dart\nfinal node = await IPFSNode.create(\n  IPFSConfig(\n    dataDir: './gateway_data',\n    offline: true,\n    gateway: GatewayConfig(\n      enabled: true,\n      port: 8080,\n    ),\n  ),\n);\n\nawait node.start();\nprint('Gateway running at http://localhost:8080');\n// Access content at: `http://localhost:8080/ipfs/\u003cCID\u003e`\n```\n\n#### P2P Network Mode (Full Node)\n\n```dart\nfinal node = await IPFSNode.create(\n  IPFSConfig(\n    dataDir: './p2p_data',\n    offline: false,  // Enable P2P networking\n    network: NetworkConfig(\n      bootstrapPeers: [\n        '/dnsaddr/bootstrap.libp2p.io/p2p/...',\n      ],\n      enableNatTraversal: true,  // UPnP/NAT-PMP\n    ),\n  ),\n);\n\nawait node.start();\nprint('P2P Node ID: ${node.peerID}');\n// Node participates in DHT, Bitswap, PubSub\n```\n\n#### Web Platform (Browser)\n\n```dart\nimport 'package:dart_ipfs/src/core/ipfs_node/ipfs_web_node.dart';\n\nvoid main() async {\n  final node = IPFSWebNode(\n    bootstrapPeers: ['wss://relay.node.address/p2p/...'],\n  );\n  await node.start();\n\n  final cid = await node.add(Uint8List.fromList('Hello Web!'.codeUnits));\n  print('Added: $cid');\n\n  final data = await node.get(cid.encode());\n  print('Retrieved: ${String.fromCharCodes(data!)}');\n}\n```\n\n---\n\n## Configuration\n\n### Full Configuration Reference\n\n```dart\nIPFSConfig(\n  // Storage\n  dataDir: './ipfs_data',\n\n  // Networking\n  offline: false,\n  network: NetworkConfig(\n    bootstrapPeers: [...],\n    listenAddresses: ['/ip4/0.0.0.0/tcp/4001'],\n    enableNatTraversal: true,  // UPnP/NAT-PMP port mapping\n  ),\n\n  // Gateway\n  gateway: GatewayConfig(\n    enabled: true,\n    port: 8080,\n    writable: false,\n    cacheSize: 1024 * 1024 * 1024,  // 1GB\n  ),\n\n  // RPC API\n  rpc: RPCConfig(\n    enabled: true,\n    port: 5001,\n  ),\n\n  // DHT\n  dht: DHTConfig(\n    mode: DHTMode.server,  // client, server, or auto\n    bucketSize: 20,\n  ),\n\n  // Security\n  security: SecurityConfig(\n    dhtDifficulty: 16,              // S/Kademlia PoW difficulty\n    rateLimitWindow: Duration(minutes: 1),\n    maxAuthAttempts: 5,\n    keyRotationInterval: Duration(days: 30),\n  ),\n\n  // Logging\n  debug: false,\n  verboseLogging: false,\n)\n```\n\n---\n\n## Use Cases\n\n### 1. Decentralized Storage\n\n```dart\nfinal file = File('document.pdf');\nfinal bytes = await file.readAsBytes();\nfinal cid = await node.addBytes(bytes);\nprint('Document CID: $cid');\n// Content is permanently addressable\n```\n\n### 2. Content Distribution Network\n\n```dart\nfinal config = IPFSConfig(\n  gateway: GatewayConfig(\n    enabled: true,\n    port: 8080,\n    cacheSize: 1024 * 1024 * 1024,\n  ),\n);\n```\n\n### 3. Peer-to-Peer Applications\n\n```dart\n// PubSub messaging\nawait node.pubsub.subscribe('my-topic', (message) {\n  print('Received: $message');\n});\n\nawait node.pubsub.publish('my-topic', 'Hello, peers!');\n```\n\n### 4. Decentralized Websites\n\n```dart\nfinal websiteDir = Directory('./my-website');\nfinal rootCID = await node.addDirectory(websiteDir);\n// Access via: `http://gateway/ipfs/\u003crootCID\u003e/index.html`\n```\n\n---\n\n## Architecture\n\n`dart_ipfs` follows a **Manager-Handler** pattern, coordinated by a `LifecycleManager`. This architecture ensures modularity, where each major responsibility (Content, Network, Protocol, Security, Storage) is handled by a specialized manager.\n\nThe **`IpfsPlatform`** abstraction layer shields the core logic from platform-specific differences, automatically switching between `dart:io` (for Desktop/Server) and `dart:html`/`idb_shim` (for Web) implementations.\n\n```\n┌─────────────────────────────────────┐\n│         Application Layer            │\n│   (Your Dart/Flutter Application)    │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│         dart_ipfs Public API         │\n│  (IPFSNode Facade \u0026 IpfsPlatform)    │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│         Service Layer                │\n│ (Managers: Content, Network, etc.)  │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│        Protocol Layer                │\n│  Bitswap │ DHT │ GraphSync │ Relay  │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│        Transport Layer               │\n│        P2P (Native libp2p)           │\n│  AutoNAT │ Circuit Relay v2           │\n│  Crypto (Ed25519 + Noise)            │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│         Storage Layer                │\n│ (Providers: FileStore vs IndexedDB) │\n└─────────────────────────────────────┘\n```\n\nFor more details, see the **[Architecture Guide](doc/ARCHITECTURE.md)**.\n\n---\n\n## 🛡️ Security\n\n\u003e **IMPORTANT**: Production use requires strict sandboxing.\n\u003e See `docker-compose.yml` for a secure reference implementation.\n\n### Recommended Deployment\n\n1.  **Immutable Filesystem**: Run with a read-only root\n2.  **Non-Root Execution**: Use UID \u003e 1000 (e.g., `10001`)\n3.  **Network Isolation**: Bind ports to localhost (`127.0.0.1`) only\n4.  **IP Diversity Limits**: Max 5 peers/IP to prevent routing table poisoning\n\n### Encrypted Keystore\n\n```dart\n// Unlock keystore with password\nawait node.securityManager.unlockKeystore('your-password');\n\n// Keys are encrypted at rest with AES-256-GCM\n// Master key derived via PBKDF2\n// Automatic memory zeroing on lock\n```\n\n### S/Kademlia PoW\n\n```dart\n// Enable Sybil protection in DHT\nSecurityConfig(\n  dhtDifficulty: 16,  // Require 16-bit PoW prefix\n)\n// Peers with insufficient PoW are rejected from routing table\n```\n\n---\n\n## Performance\n\n| Metric          | Value                   |\n| --------------- | ----------------------- |\n| Content Hashing | ~50 MB/s (SHA-256)      |\n| Block Storage   | ~1000 ops/sec (Hive)    |\n| Gateway Latency | \u003c10ms (local cache hit) |\n| P2P Handshake   | \u003c100ms (secp256k1 ECDH) |\n| Memory Baseline | ~50MB + content cache   |\n\n---\n\n## Known Limitations\n\nNone.\n\n---\n\n## Troubleshooting\n\n### Node Won't Start (Windows)\n\n**Symptom**: Hangs during startup\n\n**Solution**: Install libsodium:\n\n```powershell\nwinget install jedisct1.libsodium\n```\n\n### AutoNAT Reports \"Symmetric\"\n\n**Symptom**: Peers can't connect to you\n\n**Solution**: Enable port mapping:\n\n```dart\nNetworkConfig(enableNatTraversal: true)\n```\n\n### DHT Queries Slow\n\n**Symptom**: `findProviders` takes \u003e30s\n\n**Solution**: Ensure bootstrap peers are reachable and check `dhtDifficulty` isn't too high.\n\n### Gateway Returns 404\n\n**Symptom**: Content not found even though added\n\n**Solution**: Check if content is pinned:\n\n```dart\nawait node.pin(cid);\n```\n\n---\n\n## Examples\n\nSee the `example/` directory for full applications:\n\n- **[📱 Premium Dashboard](example/ipfs_dashboard)**: Flutter desktop app with glassmorphism UI\n- **[📟 CLI Dashboard](example/cli_dashboard)**: Matrix-style terminal interface\n\nOther examples:\n\n- [Basic Usage](example/dart_ipfs_example.dart)\n- [Offline Blog](example/blog_use_case.dart)\n- [P2P Networking](example/online_test.dart)\n- [HTTP Gateway](example/gateway_example.dart)\n- [Full Node](example/full_node_example.dart)\n- [Keystore Unlock](example/keystore_unlock_example.dart)\n- [libp2p Bridge Verification](example/verify_bridge.dart)\n\nRun examples:\n\n```bash\ndart run example/blog_use_case.dart\ndart run example/online_test.dart\n```\n\n---\n\n## Testing\n\n```bash\n# Run all tests (VM)\ndart test\n\n# Run tests in Chrome (Web)\ndart test -p chrome\n\n# Run with verbose output\ndart test -r expanded\n\n# Static analysis\ndart analyze\n```\n\nExpected results:\n\n- ✅ 0 errors\n- ✅ 0 warnings\n- ✅ 2326 tests pass\n\n---\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Write tests for new features\n4. Ensure `dart analyze` and `dart test` pass\n5. Submit a pull request\n\n---\n\n## Roadmap\n\n### ✅ Done\n\n- Core IPFS protocols (Bitswap, DHT, PubSub)\n- Offline, Gateway, and P2P modes\n- Production cryptography\n- Web platform support\n  - WebSocket, WebRTC, and WebTransport\n  - WebRTC-Direct for browser-to-browser P2P\n- libp2p core migration\n- Circuit Relay v2\n- AutoNAT\n- Encrypted keystore\n- S/Kademlia PoW\n- 95%+ Router Coverage\n\n### 🔄 In Progress\n\n- Mobile optimization (Flutter performance)\n- Native QUIC transport (Desktop/Server)\n\n### 📋 Planned\n\n- Filecoin integration\n- IPFS Pinning Service API (Remote Pinning)\n\n---\n\n## Comparison with go-ipfs\n\n| Feature          | dart_ipfs   | go-ipfs (Kubo) |\n| ---------------- | ----------- | -------------- |\n| Content Storage  | ✅          | ✅             |\n| UnixFS           | ✅          | ✅             |\n| CID v0/v1        | ✅          | ✅             |\n| Bitswap 1.2.0    | ✅          | ✅             |\n| Kademlia DHT     | ✅          | ✅             |\n| HTTP Gateway     | ✅          | ✅             |\n| RPC API          | ✅          | ✅             |\n| PubSub           | ✅          | ✅             |\n| IPNS             | ✅          | ✅             |\n| GraphSync        | ✅          | ✅             |\n| Circuit Relay v2 | ✅          | ✅             |\n| AutoNAT          | ✅          | ✅             |\n| Language         | Dart        | Go             |\n| Mobile Support   | ✅ Flutter  | ❌             |\n| Web Support      | ✅ Dart Web | ❌             |\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE) file for details\n\n---\n\n## Credits\n\nBuilt with:\n\n- [dart_libp2p](https://pub.dev/packages/dart_libp2p) — Native P2P networking\n- [pointycastle](https://pub.dev/packages/pointycastle) — Cryptography\n- [hive](https://pub.dev/packages/hive) — Storage\n- [protobuf](https://pub.dev/packages/protobuf) — Protocol buffers\n\nInspired by:\n\n- [go-ipfs (Kubo)](https://github.com/ipfs/kubo) — Reference implementation\n- [js-ipfs](https://github.com/ipfs/js-ipfs) — JavaScript implementation\n\n---\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/jxoesneon/IPFS/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/jxoesneon/IPFS/discussions)\n- **IPFS Docs**: [docs.ipfs.tech](https://docs.ipfs.tech/)\n\n---\n\n**Ready to build decentralized applications? Get started with dart_ipfs today!** 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjxoesneon%2Fipfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjxoesneon%2Fipfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjxoesneon%2Fipfs/lists"}