@newfadel/libsignal-node/README.md

Signal protocol implementation for Node.js - A ratcheting forward secrecy protocol for secure messaging

# libsignal-node

Signal protocol implementation for Node.js based on [libsignal-protocol-javascript](https://github.com/WhisperSystems/libsignal-protocol-javascript).

[![npm](https://img.shields.io/npm/v/libsignal-node.svg)](https://www.npmjs.com/package/libsignal-node)
[![npm](https://img.shields.io/npm/l/libsignal-node.svg)](https://github.com/yourusername/libsignal-node)

## Overview

A ratcheting forward secrecy protocol that works in synchronous and asynchronous messaging environments. This library is commonly used with [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys) for WhatsApp Web automation.

## Installation

\`\`\`bash
npm install libsignal-node
\`\`\`

## Usage

\`\`\`javascript
const { 
  keyhelper, 
  SessionBuilder, 
  SessionCipher, 
  ProtocolAddress 
} = require('libsignal-node');

// Generate identity key pair
const identityKeyPair = keyhelper.generateIdentityKeyPair();

// Generate registration ID
const registrationId = keyhelper.generateRegistrationId();

// Generate prekeys
const preKey = keyhelper.generatePreKey(1);
const signedPreKey = keyhelper.generateSignedPreKey(identityKeyPair, 1);

// Create protocol address
const address = new ProtocolAddress('user@example.com', 1);

// Initialize session builder
const sessionBuilder = new SessionBuilder(storage, address);

// Initialize session cipher
const sessionCipher = new SessionCipher(storage, address);
\`\`\`

## PreKeys

This 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.

At 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.

## Sessions

Signal 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.

Sessions are established in one of two ways:

1. **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.
2. **PreKeySignalMessages**: A client can receive a PreKeySignalMessage from a recipient and use it to establish a session.

## State

An 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.

State is kept in the following places:

- **Identity State**: Clients will need to maintain the state of their own identity key pair, as well as identity keys received from other clients.
- **PreKey State**: Clients will need to maintain the state of their generated PreKeys.
- **Signed PreKey States**: Clients will need to maintain the state of their signed PreKeys.
- **Session State**: Clients will need to maintain the state of the sessions they have established.

## API Reference

### keyhelper

- `generateIdentityKeyPair()`: Generate identity key pair
- `generateRegistrationId()`: Generate registration ID
- `generateSignedPreKey(identityKeyPair, signedKeyId)`: Generate signed prekey
- `generatePreKey(keyId)`: Generate prekey

### ProtocolAddress

- `new ProtocolAddress(id, deviceId)`: Create protocol address
- `ProtocolAddress.from(encodedAddress)`: Create from encoded string

### SessionBuilder

- `new SessionBuilder(storage, protocolAddress)`: Create session builder
- `initOutgoing(device)`: Initialize outgoing session
- `initIncoming(record, message)`: Initialize incoming session

### SessionCipher

- `new SessionCipher(storage, protocolAddress)`: Create session cipher
- `encrypt(data)`: Encrypt data
- `decryptWhisperMessage(data)`: Decrypt whisper message
- `decryptPreKeyWhisperMessage(data)`: Decrypt prekey whisper message

## Storage Interface

You need to implement a storage interface with the following methods:

\`\`\`javascript
const storage = {
  // Identity key methods
  getOurIdentity: () => Promise<KeyPair>,
  getOurRegistrationId: () => Promise<number>,
  isTrustedIdentity: (identifier, identityKey) => Promise<boolean>,
  
  // Session methods
  loadSession: (identifier) => Promise<SessionRecord>,
  storeSession: (identifier, record) => Promise<void>,
  
  // PreKey methods
  loadPreKey: (keyId) => Promise<KeyPair>,
  removePreKey: (keyId) => Promise<void>,
  loadSignedPreKey: (keyId) => Promise<KeyPair>
};
\`\`\`

## License

Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html

- Copyright 2015-2016 Open Whisper Systems
- Copyright 2017-2018 Forsta Inc

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
\`\`\`

```text file=".npmignore"
# Development files
.eslintrc.json
yarn.lock
generate-proto.sh

# Test files
test/
tests/
*.test.js
*.spec.js

# Development dependencies
node_modules/
.nyc_output/
coverage/

# IDE files
.vscode/
.idea/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

# Git files
.git/
.gitignore

# CI files
.travis.yml
.github/