{"id":30809582,"url":"https://github.com/raphaelvserafim/libsignal","last_synced_at":"2026-05-01T21:35:19.834Z","repository":{"id":313428007,"uuid":"1051400417","full_name":"raphaelvserafim/libsignal","owner":"raphaelvserafim","description":"Modern TypeScript implementation of the Signal Protocol for Node.js","archived":false,"fork":false,"pushed_at":"2025-11-10T19:23:20.000Z","size":76,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-23T13:00:48.363Z","etag":null,"topics":["libsignal","libsignal-protocol-javascript","nodejs","signal","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raphaelvserafim.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T23:34:42.000Z","updated_at":"2025-11-11T10:32:41.000Z","dependencies_parsed_at":"2025-09-06T01:19:34.119Z","dependency_job_id":"911b7e1b-59ff-4b6e-b46a-8e6ffe5035af","html_url":"https://github.com/raphaelvserafim/libsignal","commit_stats":null,"previous_names":["raphaelvserafim/libsignal"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/raphaelvserafim/libsignal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelvserafim%2Flibsignal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelvserafim%2Flibsignal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelvserafim%2Flibsignal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelvserafim%2Flibsignal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raphaelvserafim","download_url":"https://codeload.github.com/raphaelvserafim/libsignal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphaelvserafim%2Flibsignal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32513954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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":["libsignal","libsignal-protocol-javascript","nodejs","signal","typescript"],"created_at":"2025-09-06T04:46:30.764Z","updated_at":"2026-05-01T21:35:19.810Z","avatar_url":"https://github.com/raphaelvserafim.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libsignal Node (TypeScript)\n\n**Modern TypeScript implementation of the Signal Protocol for Node.js**\n\nA robust, type-safe, and updated version of the Signal protocol implementation, originally based on [libsignal-protocol-javascript](https://github.com/WhisperSystems/libsignal-protocol-javascript), now fully migrated to TypeScript for enhanced developer experience and reliability.\n\n## 🚀 What's New in v3.0\n\n- **Full TypeScript Support**: Complete migration from JavaScript to TypeScript with comprehensive type definitions\n- **Enhanced Type Safety**: Strict typing throughout the codebase prevents runtime errors\n- **Modern ES Modules**: Support for both CommonJS and ES module imports\n- **Improved Developer Experience**: IntelliSense, auto-completion, and compile-time error checking\n- **Updated Dependencies**: Latest versions of all dependencies for security and performance\n- **Robust Architecture**: Cleaner, more maintainable code structure\n\n## 📦 Installation\n\n```bash\nnpm install @raphaelvserafim/libsignal\n```\n\n## 🛠️ Usage\n\n### TypeScript\n```typescript\nimport { SessionBuilder, SessionCipher, ProtocolAddress, keyhelper } from '@raphaelvserafim/libsignal';\n\n// Generate identity key pair\nconst identityKeyPair = keyhelper.generateIdentityKeyPair();\n\n// Create protocol address\nconst address = new ProtocolAddress('user123', 1);\n\n// Build session\nconst sessionBuilder = new SessionBuilder(storage, address);\nawait sessionBuilder.initOutgoing(preKeyBundle);\n\n// Encrypt/decrypt messages\nconst cipher = new SessionCipher(storage, address);\nconst encrypted = await cipher.encrypt(Buffer.from('Hello, Signal!'));\n```\n\n### JavaScript (CommonJS)\n```javascript\nconst { SessionBuilder, SessionCipher, ProtocolAddress, keyhelper } = require('@raphaelvserafim/libsignal');\n\n// Same API as TypeScript examples\n```\n\n## 📋 Overview\n\nA ratcheting forward secrecy protocol that works in synchronous and asynchronous messaging environments. This TypeScript implementation provides:\n\n- **Type Safety**: Compile-time guarantees for protocol correctness\n- **Modern Async/Await**: Clean asynchronous code patterns\n- **Comprehensive Error Handling**: Typed error classes for better debugging\n- **Memory Safety**: Proper buffer handling and cleanup\n\n## 🔑 PreKeys\n\nThis protocol uses a concept called 'PreKeys'. A PreKey is an ECPublicKey and an associated unique ID which are stored together by a server. PreKeys can also be signed.\n\nAt install time, clients generate a single signed PreKey, as well as a large list of unsigned PreKeys, and transmit all of them to the server.\n\n```typescript\n// Generate PreKeys\nconst preKeys = [];\nfor (let i = 0; i \u003c 100; i++) {\n    preKeys.push(keyhelper.generatePreKey(i));\n}\n\n// Generate signed PreKey\nconst signedPreKey = keyhelper.generateSignedPreKey(identityKeyPair, 1);\n```\n\n## 🔗 Sessions\n\nSignal Protocol is session-oriented. Clients establish a \"session,\" which is then used for all subsequent encrypt/decrypt operations. There is no need to ever tear down a session once one has been established.\n\nSessions are established in one of two ways:\n\n1. **PreKeyBundles**: A client that wishes to send a message to a recipient can establish a session by retrieving a PreKeyBundle for that recipient from the server.\n2. **PreKeySignalMessages**: A client can receive a PreKeySignalMessage from a recipient and use it to establish a session.\n\n```typescript\ninterface PreKeyBundle {\n    registrationId: number;\n    deviceId: number;\n    preKeyId?: number;\n    preKeyPublic?: ArrayBuffer;\n    signedPreKeyId: number;\n    signedPreKeyPublic: ArrayBuffer;\n    signedPreKeySignature: ArrayBuffer;\n    identityKey: ArrayBuffer;\n}\n```\n\n## 💾 State Management\n\nAn established session encapsulates a lot of state between two clients. That state is maintained in durable records which need to be kept for the life of the session.\n\nState is kept in the following places:\n\n- **Identity State**: Clients maintain their own identity key pair and identity keys from other clients\n- **PreKey State**: Clients maintain the state of their generated PreKeys\n- **Signed PreKey States**: Clients maintain the state of their signed PreKeys  \n- **Session State**: Clients maintain the state of established sessions\n\n```typescript\ninterface SignalProtocolStore {\n    // Identity management\n    getIdentityKeyPair(): Promise\u003cKeyPair\u003e;\n    getLocalRegistrationId(): Promise\u003cnumber\u003e;\n    saveIdentity(name: string, identityKey: ArrayBuffer): Promise\u003cboolean\u003e;\n    isTrustedIdentity(name: string, identityKey: ArrayBuffer, direction: Direction): Promise\u003cboolean\u003e;\n    \n    // PreKey management\n    loadPreKey(keyId: number): Promise\u003cKeyPair | undefined\u003e;\n    storePreKey(keyId: number, keyPair: KeyPair): Promise\u003cvoid\u003e;\n    removePreKey(keyId: number): Promise\u003cvoid\u003e;\n    \n    // Session management\n    loadSession(identifier: string): Promise\u003cSessionRecord | undefined\u003e;\n    storeSession(identifier: string, record: SessionRecord): Promise\u003cvoid\u003e;\n    removeSession(identifier: string): Promise\u003cvoid\u003e;\n}\n```\n\n## 🏗️ Project Structure\n\n```\n📦libsignal\n ┣ 📂src\n ┃ ┣ 📂constants      # Protocol constants and enums\n ┃ ┣ 📂crypto         # Cryptographic operations\n ┃ ┣ 📂protocol       # Core protocol implementation\n ┃ ┣ 📂types          # TypeScript type definitions\n ┃ ┣ 📂utils          # Utility functions and helpers\n ┃ ┣ 📂whisper        # Protocol buffer definitions\n ┃ ┗ 📜index.ts       # Main entry point\n ┣ 📂dist             # Compiled JavaScript output\n ┣ 📜tsconfig.json    # TypeScript configuration\n ┗ 📜package.json     # Package configuration\n```\n\n## 🔧 Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## 📄 API Reference\n\n### Core Classes\n\n- `SessionBuilder` - Establishes encrypted sessions between clients\n- `SessionCipher` - Encrypts and decrypts messages within sessions\n- `ProtocolAddress` - Represents a unique client address\n- `SessionRecord` - Maintains session state and history\n\n### Utilities\n\n- `keyhelper` - Key generation utilities\n- `crypto` - Low-level cryptographic functions\n- `curve` - Elliptic curve operations\n- `errors` - Typed error classes\n\n### Types\n\nAll classes and functions include comprehensive TypeScript definitions for enhanced development experience.\n\n## 🔒 Security\n\nThis implementation maintains the same security properties as the original Signal Protocol:\n\n- **Forward Secrecy**: Past communications remain secure even if keys are compromised\n- **Future Secrecy**: Future communications remain secure after key compromise\n- **Deniability**: Messages cannot be cryptographically proven to have come from a specific sender\n\n## 📜 License\n\nLicensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html\n\n* Copyright 2015-2016 Open Whisper Systems\n* Copyright 2017-2018 Forsta Inc\n* Copyright 2023-2024 Raphael Serafim - TypeScript Migration\n\n## 🤝 Contributing\n\nContributions are welcome! Please ensure all code follows TypeScript best practices and includes appropriate type definitions.\n\n## 📞 Support\n\nFor issues, questions, or contributions, please visit the [GitHub repository](https://github.com/raphaelvserafim/libsignal).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelvserafim%2Flibsignal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraphaelvserafim%2Flibsignal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphaelvserafim%2Flibsignal/lists"}