@akaanakbaik/libsignal

Modernized, security-hardened fork of the Signal Protocol for Node.js

---

Overview

@akaanakbaik/libsignal is a pure JavaScript implementation of the Signal Protocol — the cryptographic protocol that powers WhatsApp, Signal Messenger, and other end-to-end encrypted messaging applications.

This is a modernized fork of WhiskeySockets/libsignal-node. It provides:

• Zero Breaking Changes — 100% API compatible with the original
• Security Hardened — All sensitive data leakage via console logging removed
• Enterprise Quality — Comprehensive testing, CI/CD, and documentation
• Long-Term Maintainable — Clean codebase with full documentation

Features

• 🔐 Signal Protocol v3 — X3DH key agreement + Double Ratchet algorithm
• 🔑 X25519 Key Agreement — Curve25519 ECDH for forward secrecy
• 📝 Ed25519 Signatures — Signed pre-keys for identity verification
• 🗄️ AES-256-CBC Encryption — Symmetric message encryption
• 🔄 Session Management — Multi-session support with cleanup
• 📦 Pure JavaScript — No native compilation required
• 🎯 Baileys Compatible — Drop-in replacement for @kelvdra/baileys

Why This Fork?

The original WhiskeySockets/libsignal-node package:

1. Leaks sensitive data: Console.log/info/warn calls expose private keys, session records, and registration IDs to stdout/stderr
2. Lacks testing: No unit tests, no regression tests, no CI/CD
3. Limited documentation: No API reference, architecture docs, or security guide
4. No publish config: Git URL dependencies cause installation issues

This fork addresses all these issues while maintaining 100% backward compatibility.

Installation

npm install @akaanakbaik/libsignal

Usage

Basic Usage

const libsignal = require('@akaanakbaik/libsignal');

// OR (ESM / TypeScript)
import * as libsignal from '@akaanakbaik/libsignal';

With Baileys

// Works with @kelvdra/baileys and WhiskeySockets/Baileys
const libsignal = require('@akaanakbaik/libsignal');

// Or configure your Baileys instance to use this package

Key Generation

const { keyhelper, curve, ProtocolAddress } = require('@akaanakbaik/libsignal');

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

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

// Generate signed pre-key
const signedPreKey = keyhelper.generateSignedPreKey(identityKeyPair, 1);

// Generate one-time pre-key
const preKey = keyhelper.generatePreKey(1);

Session Establishment

const { SessionBuilder, SessionCipher, ProtocolAddress } = require('@akaanakbaik/libsignal');

// Create address for remote device
const remoteAddr = new ProtocolAddress('user@example.com', 1);

// Storage interface (implement by your app)
const storage = {
    loadSession: async (id) => { /* ... */ },
    storeSession: async (id, session) => { /* ... */ },
    isTrustedIdentity: (identifier, identityKey) => { /* ... */ },
    loadPreKey: async (id) => { /* ... */ },
    removePreKey: (id) => { /* ... */ },
    loadSignedPreKey: () => { /* ... */ },
    getOurRegistrationId: () => { /* ... */ },
    getOurIdentity: () => { /* ... */ }
};

// Initiate session
const builder = new SessionBuilder(storage, remoteAddr);
await builder.initOutgoing({
    registrationId: 12345,
    identityKey: someIdentityKey,
    signedPreKey: { keyId: 1, publicKey: pubKey, signature: sig },
    preKey: { keyId: 1, publicKey: pubKey }
});

Message Encryption/Decryption

const cipher = new SessionCipher(storage, remoteAddr);

// Encrypt
const { type, body, registrationId } = await cipher.encrypt(
    Buffer.from('Hello, World!')
);

// Decrypt (standard message)
const plaintext = await cipher.decryptWhisperMessage(body);

// Decrypt (pre-key message)
const plaintext = await cipher.decryptPreKeyWhisperMessage(preKeyMessage);

API

Exports

Export	Description
crypto	AES-256-CBC, HMAC-SHA256, SHA-512, HKDF
curve	X25519 key agreement, Ed25519 signatures
keyhelper	Key generation (identity, pre-keys, signed pre-keys)
ProtocolAddress	Device address representation
SessionBuilder	Session establishment (X3DH)
SessionCipher	Message encryption/decryption (Double Ratchet)
SessionRecord	Session state persistence
SignalError	Base error class
UntrustedIdentityKeyError	Untrusted identity error
SessionError	Session error
MessageCounterError	Message counter error
PreKeyError	Pre-key error

For full API documentation, see API_REFERENCE.md.

Migration Guide

From libsignal (npm) or WhiskeySockets/libsignal-node

1. Update your package.json:

{
  "dependencies": {
    "libsignal": "npm:@akaanakbaik/libsignal@^1.0.0"
  }
}

2. Or replace the package name:

{
  "dependencies": {
    "@akaanakbaik/libsignal": "^1.0.0"
  }
}

3. Update your imports:

// Old
const libsignal = require('libsignal');

// New
const libsignal = require('@akaanakbaik/libsignal');

No other code changes required. All APIs, classes, methods, parameters, return values, and error types are identical.

Compatibility Matrix

Node.js Versions

Version	Supported
16.x	✅
18.x	✅
20.x	✅
22.x	✅
24.x	⏳ (planned)

Baileys Versions

Version	Compatible
WhiskeySockets/Baileys 6.x	✅
@kelvdra/baileys 1.x	✅

Platforms

Platform	Architecture	Status
Ubuntu 20.04+	x64, arm64	✅
Debian 11+	x64, arm64	✅
macOS 12+	x64, arm64	✅
Windows Server 2019+	x64	✅
Windows 10+	x64	✅

Security

What We Fixed

• Removed all console.log/info/warn/error calls that leaked:
  • Private keys
  • Ephemeral keys
  • Root keys
  • Pending pre-keys
  • Registration IDs
  • Session records
  • Error stack traces

What We Guarantee

• Zero sensitive data printed to stdout/stderr
• Zero cryptographic changes — protocol behavior is identical
• Zero API changes — 100% backward compatible
• Regression tests ensure no console logging is reintroduced

See SECURITY.md for vulnerability reporting and SECURITY_ARCHITECTURE.md for detailed security analysis.

Performance

Benchmarks available in test/benchmark.test.js.

Run benchmarks:

node --test test/benchmark.test.js

Development

# Clone
git clone https://github.com/akaanakbaik/libsignal.git
cd libsignal

# Install
npm install

# Test
npm test

# Lint
npx eslint src/
npx prettier --check "src/**/*.js" "index.js"

See DEVELOPMENT_GUIDE.md for full development setup.

Documentation Index

Document	Description
README.md	This file
API_REFERENCE.md	Complete API documentation
ARCHITECTURE.md	Architecture overview
DESIGN.md	Design decisions and rationale
INTERNALS.md	Internal implementation details
SECURITY_ARCHITECTURE.md	Security analysis
SECURITY.md	Security policy and vulnerability reporting
CONTRIBUTING.md	Contributing guidelines
DEVELOPMENT_GUIDE.md	Development setup
TESTING_GUIDE.md	Testing guide
RELEASE_GUIDE.md	Release process
CHANGELOG.md	Version history
ROADMAP.md	Future plans
AGENTS.md	AI/Agent guide
LAPORAN.md	Master audit report

FAQ

Why does this package exist?

The original WhiskeySockets/libsignal-node had several issues: sensitive data leaked through console logs, no testing, no CI/CD, and limited documentation. This fork addresses all these issues while maintaining 100% backward compatibility.

Is this compatible with Baileys?

Yes. This is designed as a drop-in replacement for the libsignal dependency in @kelvdra/baileys. No code changes needed.

Does this change the Signal Protocol?

No. Zero changes to cryptographic algorithms, session format, message format, serialization, or any protocol behavior.

Can I use this with the official Signal app?

No. This is a Node.js implementation for server-side use. The official Signal app uses @signalapp/libsignal-client.

Why not use @signalapp/libsignal-client?

The official library uses native Rust bindings and has a different API. Switching would require significant changes to Baileys.

Will this package receive updates?

Yes. We maintain this package for the @kelvdra/baileys project and welcome community contributions.

License

GPL-3.0 — This is a fork of WhiskeySockets/libsignal-node, which is licensed under GPL-3.0.

Credits

• WhiskeySockets — Original libsignal-node implementation
• Adiwajshing — Original Baileys project
• Signal Foundation — The Signal Protocol specification

Support

• GitHub Issues
• Security Issues
• Documentation