{"id":29543126,"url":"https://github.com/quiint/expo-bitchat","last_synced_at":"2025-08-23T02:17:33.962Z","repository":{"id":304764345,"uuid":"1019875774","full_name":"quiint/expo-bitchat","owner":"quiint","description":"The Expo library to incorporate Bitchat functionality into your mobile app.","archived":false,"fork":false,"pushed_at":"2025-07-15T02:50:01.000Z","size":231,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T09:39:52.462Z","etag":null,"topics":["bitchat","bitchat-android","bitchat-js","expo","react-native"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/expo-bitchat","language":"Swift","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/quiint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T02:41:28.000Z","updated_at":"2025-08-07T09:45:42.000Z","dependencies_parsed_at":"2025-07-15T07:30:51.427Z","dependency_job_id":"0073a227-60ef-458f-bcd9-37170da361e7","html_url":"https://github.com/quiint/expo-bitchat","commit_stats":null,"previous_names":["quiint/expo-bitchat"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/quiint/expo-bitchat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiint%2Fexpo-bitchat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiint%2Fexpo-bitchat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiint%2Fexpo-bitchat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiint%2Fexpo-bitchat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quiint","download_url":"https://codeload.github.com/quiint/expo-bitchat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiint%2Fexpo-bitchat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271732362,"owners_count":24811309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bitchat","bitchat-android","bitchat-js","expo","react-native"],"created_at":"2025-07-17T13:02:48.353Z","updated_at":"2025-08-23T02:17:33.947Z","avatar_url":"https://github.com/quiint.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# expo-bitchat\n\n\u003e [!WARNING]\n\u003e This software has not received external security review and may contain vulnerabilities and may not necessarily meet its stated security goals. Do not use it for sensitive use cases, and do not rely on its security until it has been reviewed. Work in progress.\n\n**An Expo native module for secure, decentralized, peer-to-peer messaging over Bluetooth mesh networks.**\n\nThis is the **Expo/React Native module** that provides the backend infrastructure for Bitchat mobile apps, enabling cross-platform encrypted messaging without internet, servers, or phone numbers.\n\n## Features\n\n- **✅ Cross-Platform Support**: iOS and Android native implementations\n- **✅ Bluetooth Mesh Networking**: Automatic peer discovery and multi-hop message relay\n- **✅ End-to-End Encryption**: X25519 key exchange + AES-256-GCM for private messages\n- **✅ Channel-Based Messaging**: Topic-based group chats with optional password protection\n- **✅ Store \u0026 Forward**: Messages cached for offline peers and delivered when they reconnect\n- **✅ Privacy First**: No accounts, no phone numbers, no persistent identifiers\n- **✅ TypeScript Support**: Full type definitions included\n- **✅ Event-Driven API**: React to messages, peer connections, and delivery status\n- **✅ Message Compression**: LZ4 compression for bandwidth efficiency\n- **✅ Battery Optimization**: Adaptive scanning and power management\n\n## Installation\n\n```sh\nbunx expo install expo-bitchat\n```\n\n### Platform Requirements\n\n- **iOS**: iOS 13.0+ with Bluetooth LE support\n- **Android**: API level 26 (Android 8.0+) with Bluetooth LE support\n- **Expo**: SDK 50+ (uses new architecture modules)\n\n### Permissions\n\nThe module requires the following permissions (configured in your app.json/app.config.js):\n\n#### iOS (Info.plist)\n\n```xml\n\u003ckey\u003eNSBluetoothAlwaysUsageDescription\u003c/key\u003e\n\u003cstring\u003eThis app uses Bluetooth for secure peer-to-peer messaging\u003c/string\u003e\n\u003ckey\u003eNSBluetoothPeripheralUsageDescription\u003c/key\u003e\n\u003cstring\u003eThis app uses Bluetooth for mesh networking\u003c/string\u003e\n```\n\n#### Android (AndroidManifest.xml)\n\n```xml\n\u003cuses-permission android:name=\"android.permission.BLUETOOTH\" /\u003e\n\u003cuses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\" /\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e\n\u003cuses-permission android:name=\"android.permission.BLUETOOTH_ADVERTISE\" /\u003e\n\u003cuses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\" /\u003e\n\u003cuses-permission android:name=\"android.permission.BLUETOOTH_SCAN\" /\u003e\n```\n\n## Usage\n\n### Basic Setup\n\n```typescript\nimport BitchatAPI, { BitchatMessage } from \"expo-bitchat\";\n\n// Start the mesh service with your nickname\nawait BitchatAPI.startServices(\"YourNickname\");\n\n// Listen for incoming messages\nconst messageSubscription = BitchatAPI.addMessageListener(\n  (message: BitchatMessage) =\u003e {\n    console.log(\"Received message:\", message.content);\n    console.log(\"From:\", message.sender);\n    console.log(\"Channel:\", message.channel);\n  }\n);\n\n// Send a public message\nawait BitchatAPI.sendMessage(\"Hello mesh network!\", [], \"#general\");\n\n// Send a private message\nconst peers = await BitchatAPI.getConnectedPeers();\nconst peerID = Object.keys(peers)[0];\nawait BitchatAPI.sendPrivateMessage(\"Secret message\", peerID, peers[peerID]);\n\n// Clean up\nmessageSubscription.remove();\nawait BitchatAPI.stopServices();\n```\n\n### Event Listeners\n\n```typescript\n// Listen for peer connections\nconst peerConnectedSub = BitchatAPI.addPeerConnectedListener(\n  ({ peerID, nickname }) =\u003e {\n    console.log(`${nickname} connected`);\n  }\n);\n\n// Listen for peer disconnections\nconst peerDisconnectedSub = BitchatAPI.addPeerDisconnectedListener(\n  ({ peerID, nickname }) =\u003e {\n    console.log(`${nickname} disconnected`);\n  }\n);\n\n// Listen for delivery acknowledgments\nconst deliveryAckSub = BitchatAPI.addDeliveryAckListener((ack) =\u003e {\n  console.log(`Message delivered to ${ack.recipientNickname}`);\n});\n\n// Listen for read receipts\nconst readReceiptSub = BitchatAPI.addReadReceiptListener((receipt) =\u003e {\n  console.log(`Message read by ${receipt.readerNickname}`);\n});\n```\n\n### Channel Management\n\n```typescript\n// Set a password for a channel (owner only)\nawait BitchatAPI.setChannelPassword(\"#private-channel\", \"secretpassword\");\n\n// Remove password (owner only)\nawait BitchatAPI.setChannelPassword(\"#private-channel\");\n```\n\n### Message Types\n\n```typescript\ninterface BitchatMessage {\n  id: string;\n  sender: string;\n  content: string;\n  timestamp: number;\n  isPrivate: boolean;\n  channel?: string;\n  mentions?: string[];\n  senderPeerID?: string;\n  isEncrypted?: boolean;\n  deliveryStatus?: DeliveryStatus;\n}\n\ntype DeliveryStatus =\n  | { type: \"sending\" }\n  | { type: \"sent\" }\n  | { type: \"delivered\"; to: string; at: number }\n  | { type: \"read\"; by: string; at: number }\n  | { type: \"failed\"; reason: string };\n```\n\n## API Reference\n\n### Core Methods\n\n#### `startServices(nickname: string): Promise\u003cboolean\u003e`\n\nInitializes the Bluetooth mesh service with the given nickname.\n\n#### `stopServices(): Promise\u003cboolean\u003e`\n\nStops the mesh service and disconnects from all peers.\n\n#### `sendMessage(content: string, mentions?: string[], channel?: string): Promise\u003cvoid\u003e`\n\nSends a public message to a channel with optional @mentions.\n\n#### `sendPrivateMessage(content: string, recipientPeerID: string, recipientNickname: string): Promise\u003cvoid\u003e`\n\nSends an encrypted private message to a specific peer.\n\n#### `setChannelPassword(channel: string, password?: string): Promise\u003cvoid\u003e`\n\nSets or removes a password for a channel (channel owner only).\n\n#### `getConnectedPeers(): Promise\u003cPeerInfo\u003e`\n\nReturns a map of connected peer IDs to their nicknames.\n\n### Event Listeners\n\nAll event listeners return a `Subscription` object with a `remove()` method.\n\n- `addMessageListener(listener)` - New message received\n- `addPeerConnectedListener(listener)` - Peer joined the mesh\n- `addPeerDisconnectedListener(listener)` - Peer left the mesh\n- `addPeerListUpdatedListener(listener)` - Peer list changed\n- `addDeliveryAckListener(listener)` - Message delivery confirmed\n- `addReadReceiptListener(listener)` - Message read receipt\n- `addDeliveryStatusUpdateListener(listener)` - Message status changed\n\n## Security \u0026 Privacy\n\n### Encryption\n\n- **Private Messages**: X25519 key exchange + AES-256-GCM encryption\n- **Channel Messages**: Argon2id password derivation + AES-256-GCM\n- **Digital Signatures**: Ed25519 for message authenticity\n- **Forward Secrecy**: New key pairs generated each session\n\n### Privacy Features\n\n- **No Registration**: No accounts, emails, or phone numbers required\n- **Ephemeral by Default**: Messages exist only in device memory\n- **Cover Traffic**: Random delays and dummy messages prevent traffic analysis\n- **Local-First**: Works completely offline, no servers involved\n\n## Technical Architecture\n\n### Native Modules\n\nThe module consists of native implementations for both platforms:\n\n#### iOS Implementation\n\n- **BitchatModule.swift**: Main Expo module interface\n- **BluetoothMeshService.swift**: Core BLE mesh networking\n- **EncryptionService.swift**: Cryptographic operations\n- **BinaryProtocol.swift**: Protocol encoding/decoding\n\n#### Android Implementation\n\n- **BitchatModule.kt**: Main Expo module interface\n- **BluetoothMeshService.kt**: Core BLE mesh networking\n- **EncryptionService.kt**: Cryptographic operations\n- **BinaryProtocol.kt**: Protocol encoding/decoding\n\n### Protocol Compatibility\n\nThe module maintains 100% binary protocol compatibility between platforms:\n\n- **Header Format**: Identical packet structure\n- **Encryption**: Same cryptographic algorithms\n- **UUIDs**: Shared Bluetooth service identifiers\n- **Message Routing**: Compatible TTL and relay behavior\n\n### Performance Optimizations\n\n- **Message Compression**: LZ4 compression for messages \u003e100 bytes\n- **Battery Management**: Adaptive scanning based on battery level\n- **Connection Pooling**: Efficient peer connection management\n- **Bloom Filters**: Fast duplicate message detection\n\n## Development\n\n### Building the Module\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Run linting\nnpm run lint\n\n# Run tests\nnpm run test\n\n# Open example app\nnpm run open:ios     # iOS\nnpm run open:android # Android\n```\n\n### Example App\n\nThe module includes an example app demonstrating basic usage:\n\n```bash\ncd example\nnpm install\nnpx expo run:ios     # iOS\nnpx expo run:android # Android\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Bluetooth permissions denied**\n\n- Ensure all required permissions are added to app.json\n- Request permissions at runtime before calling `startServices()`\n\n**Messages not reaching distant peers**\n\n- Check that intermediate devices are running the mesh service\n- Verify Bluetooth is enabled and devices are in range\n- Messages have a maximum TTL of 7 hops\n\n**Connection issues on Android**\n\n- Enable location services (required for BLE scanning)\n- Disable battery optimization for your app\n- Ensure target API level is compatible\n\n## Contributing\n\nContributions are welcome! Key areas for enhancement:\n\n1. **Performance**: Battery optimization and connection reliability\n2. **Security**: Enhanced cryptographic features\n3. **Testing**: Unit and integration test coverage\n4. **Documentation**: API documentation and usage examples\n5. **Platform Support**: Additional Expo/React Native features\n\n### Development Setup\n\n1. Clone the repository\n2. Install dependencies: `npm install`\n3. Build the module: `npm run build`\n4. Test with example app: `cd example \u0026\u0026 npx expo run:ios`\n\n## License\n\nMIT\n\n---\n\nMade with [create-expo-native-module](https://github.com/expo/expo/tree/main/packages/create-expo-native-module)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiint%2Fexpo-bitchat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquiint%2Fexpo-bitchat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiint%2Fexpo-bitchat/lists"}