EfSec is a zero-knowledge end-to-end encryption library that provides a high-level TypeScript interface to the Matrix protocol's encryption standards. Built on top of @matrix-org/matrix-sdk-crypto-wasm, it offers both convenience wrappers and direct access to the underlying Matrix cryptographic primitives.
@matrix-org/matrix-sdk-crypto-wasmnpm install efsec
import {
initializeWasm,
generateIdentityKeyPair,
generateOneTimePreKeys,
createOutboundSession,
encryptMessage,
decryptMessage,
KeyStore
} from 'efsec';
// Initialize the Matrix crypto WASM module
await initializeWasm();
// Generate Matrix-compliant identity keys
const identityKeys = await generateIdentityKeyPair();
console.log('Curve25519:', identityKeys.curve25519.key);
console.log('Ed25519:', identityKeys.ed25519.key);
// Generate one-time prekeys for X3DH
const oneTimeKeys = await generateOneTimePreKeys(50);
// Create secure storage for keys
const keyStore = new KeyStore();
await keyStore.initialize();
await keyStore.storeIdentityKeys('device-1', identityKeys);
// Create session and encrypt messages
const session = await createOutboundSession(identityKeys, recipientBundle);
const message = { content: 'Hello!', timestamp: Date.now(), messageId: 'msg-1' };
const encrypted = await encryptMessage(session, message);
const decrypted = await decryptMessage(session, encrypted);
For applications needing full Matrix protocol control:
import * as MatrixCrypto from '@matrix-org/matrix-sdk-crypto-wasm';
// Initialize Matrix SDK directly
await MatrixCrypto.initAsync();
// Create OlmMachine for your user
const olmMachine = await MatrixCrypto.OlmMachine.initialize(
new MatrixCrypto.UserId('@user:domain.com'),
new MatrixCrypto.DeviceId('DEVICE123')
);
// Get identity keys from Matrix SDK
const identityKeys = olmMachine.identityKeys;
const curve25519 = identityKeys.curve25519.toBase64();
const ed25519 = identityKeys.ed25519.toBase64();
// Generate keys through outgoing requests
const requests = await olmMachine.outgoingRequests();
// Handle key upload, query, and claim requests...
EfSec provides secure client-side key storage using IndexedDB:
import { KeyStore } from '@efchatnet/efsec';
const keyStore = new KeyStore();
await keyStore.initialize();
// Store keys
const deviceId = 'my-device-1';
const identityKeys = await generateIdentityKeyPair();
await keyStore.storeIdentityKeys(deviceId, identityKeys);
// Retrieve keys
const storedKeys = await keyStore.getIdentityKeys(deviceId);
// Export/import for backup
const backup = await keyStore.exportData(deviceId);
// ... store backup securely ...
await keyStore.importData(backup);
initializeWasm(): Promise<void>Initializes the Matrix crypto WASM module. Must be called before any other functions.
generateIdentityKeyPair(): Promise<IdentityKeys>Generates Matrix-compliant identity keys (Curve25519 and Ed25519) using the Matrix SDK.
generateOneTimePreKeys(count?: number): Promise<KeyPair[]>Generates one-time prekeys through the Matrix SDK's OlmMachine. Returns available keys from outgoing upload requests.
createOutboundSession(localKeys: IdentityKeys, remoteBundle: PreKeyBundle): Promise<Session>Creates an outbound session using X3DH key exchange protocol.
encryptMessage(session: Session, message: PlaintextMessage): Promise<EncryptedMessage>Encrypts a message using Double Ratchet (Olm) or Megolm encryption.
decryptMessage(session: Session, encrypted: EncryptedMessage): Promise<PlaintextMessage>Decrypts encrypted messages while maintaining forward secrecy.
createOutboundGroupSession(): Promise<OutboundGroupSession>Creates a new Megolm group session for encrypting messages to multiple recipients.
createInboundGroupSessionFromKey(sessionKey: string): Promise<InboundGroupSession>Creates an inbound group session from a shared session key.
KeyStoreSecure IndexedDB-based storage for cryptographic keys and session state, designed for Matrix protocol compliance.
EfSec also re-exports the complete @matrix-org/matrix-sdk-crypto-wasm API for direct access when needed. This allows applications to use Matrix SDK primitives directly while maintaining compatibility with EfSec's higher-level abstractions.
EfSec follows a dual-layer architecture:
@matrix-org/matrix-sdk-crypto-wasm for full protocol controlThis design allows applications to:
import { initializeWasm, generateIdentityKeyPair, KeyStore } from 'efsec';
import * as MatrixCrypto from '@matrix-org/matrix-sdk-crypto-wasm';
// Initialize
await initializeWasm();
// High-level API for simple tasks
const identityKeys = await generateIdentityKeyPair();
const keyStore = new KeyStore();
await keyStore.storeIdentityKeys('device-1', identityKeys);
// Direct Matrix SDK for advanced features
const olmMachine = await MatrixCrypto.OlmMachine.initialize(
new MatrixCrypto.UserId('@user:example.com'),
new MatrixCrypto.DeviceId('DEVICE123')
);
// Handle key upload requests
const requests = await olmMachine.outgoingRequests();
for (const request of requests) {
if (request.type === MatrixCrypto.RequestType.KeysUpload) {
// Send request.body to your Matrix server
const response = await fetch('/matrix/keys/upload', {
method: 'POST',
body: request.body
});
await olmMachine.markRequestAsSent(request.id, request.type, await response.text());
}
}
EfSec provides specific error types for different failure modes:
import { DecryptionError, SessionError, KeyError } from 'efsec';
try {
const decrypted = await decryptMessage(session, encrypted);
} catch (error) {
if (error instanceof DecryptionError) {
// Message could not be decrypted - possibly corrupted or wrong session
console.error('Decryption failed:', error.message);
} else if (error instanceof SessionError) {
// Session-related error - may need to re-establish session
console.error('Session error:', error.message);
} else if (error instanceof KeyError) {
// Key-related error - usually requires key regeneration
console.error('Key error:', error.message);
}
}
EfSec requires modern browser features:
Supported browsers:
GNU General Public License v3.0 or later - see LICENSE file for details.
This software is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
EfSec builds on Matrix's battle-tested cryptographic implementations:
@matrix-org/matrix-sdk-crypto-wasm directlySecurity researchers are encouraged to audit EfSec's wrapper layer, though the core cryptographic operations are handled by the audited Matrix SDK.
See CHANGELOG.md for version history.
FAQs
Matrix protocol E2E encryption library with dual API approach
The npm package efsec receives a total of 1 weekly downloads. As such, efsec popularity was classified as not popular.
We found that efsec demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.