zapo-js 0.2.0 → 1.0.0

package/dist/esm/signal/group/encoding.js

@@ -0,0 +1,96 @@
+import { proto } from '../../proto.js';
+import { asBytes, asNumber, asString } from '../../util/coercion.js';
+/** Serializes a {@link SenderKeyRecord} into the Signal `SenderKeyRecordStructure` protobuf. */
+export function encodeSenderKeyRecord(record) {
+    return proto.SenderKeyRecordStructure.encode({
+        senderKeyStates: [
+            {
+                senderKeyId: record.keyId,
+                senderChainKey: {
+                    iteration: record.iteration,
+                    seed: record.chainKey
+                },
+                senderSigningKey: {
+                    public: record.signingPublicKey,
+                    private: record.signingPrivateKey
+                },
+                senderMessageKeys: (() => {
+                    const src = record.unusedMessageKeys ?? [];
+                    const arr = new Array(src.length);
+                    for (let i = 0; i < src.length; i += 1) {
+                        const messageKey = src[i];
+                        arr[i] = {
+                            iteration: messageKey.iteration,
+                            seed: messageKey.seed
+                        };
+                    }
+                    return arr;
+                })()
+            }
+        ]
+    }).finish();
+}
+function decodeSenderKeyState(state, field) {
+    if (!state.senderChainKey) {
+        throw new Error(`missing ${field}.senderChainKey`);
+    }
+    if (!state.senderSigningKey) {
+        throw new Error(`missing ${field}.senderSigningKey`);
+    }
+    return {
+        keyId: asNumber(state.senderKeyId, `${field}.senderKeyId`),
+        iteration: asNumber(state.senderChainKey.iteration, `${field}.senderChainKey.iteration`),
+        chainKey: asBytes(state.senderChainKey.seed, `${field}.senderChainKey.seed`),
+        signingPublicKey: asBytes(state.senderSigningKey.public, `${field}.senderSigningKey.public`),
+        signingPrivateKey: state.senderSigningKey.private !== null && state.senderSigningKey.private !== undefined
+            ? asBytes(state.senderSigningKey.private, `${field}.senderSigningKey.private`)
+            : undefined,
+        unusedMessageKeys: (() => {
+            const src = state.senderMessageKeys ?? [];
+            const arr = new Array(src.length);
+            for (let i = 0; i < src.length; i += 1) {
+                const messageKey = src[i];
+                arr[i] = {
+                    iteration: asNumber(messageKey.iteration, `${field}.senderMessageKeys[${i}].iteration`),
+                    seed: asBytes(messageKey.seed, `${field}.senderMessageKeys[${i}].seed`)
+                };
+            }
+            return arr;
+        })()
+    };
+}
+/**
+ * Decodes a stored sender-key blob into a {@link SenderKeyRecord}.
+ * `groupId`/`sender` are re-attached from the row key (not in the protobuf).
+ */
+export function decodeSenderKeyRecord(raw, groupId, sender) {
+    const decoded = proto.SenderKeyRecordStructure.decode(asBytes(raw, 'sender_keys.record'));
+    const state = decoded.senderKeyStates?.[0];
+    if (!state) {
+        throw new Error('missing sender_keys.record.senderKeyStates[0]');
+    }
+    const parsed = decodeSenderKeyState(state, 'sender_keys.record.senderKeyStates[0]');
+    return {
+        groupId,
+        sender,
+        keyId: parsed.keyId,
+        iteration: parsed.iteration,
+        chainKey: parsed.chainKey,
+        signingPublicKey: parsed.signingPublicKey,
+        signingPrivateKey: parsed.signingPrivateKey,
+        unusedMessageKeys: parsed.unusedMessageKeys
+    };
+}
+/** Decodes a sender-key-distribution SQL row into a {@link SenderKeyDistributionRecord}. */
+export function decodeSenderKeyDistributionRow(row) {
+    return {
+        groupId: asString(row.group_id, 'sender_key_distribution.group_id'),
+        sender: {
+            user: asString(row.sender_user, 'sender_key_distribution.sender_user'),
+            server: asString(row.sender_server, 'sender_key_distribution.sender_server'),
+            device: asNumber(row.sender_device, 'sender_key_distribution.sender_device')
+        },
+        keyId: asNumber(row.key_id, 'sender_key_distribution.key_id'),
+        timestampMs: asNumber(row.timestamp_ms, 'sender_key_distribution.timestamp_ms')
+    };
+}

package/dist/esm/signal/index.js

@@ -1,4 +1,7 @@
-export { decodeSignalPreKeyRow, decodeSignalRegistrationRow, decodeSignalRemoteIdentity, decodeSignalSessionRecord, decodeSignalSignedPreKeyRow, decodeSenderKeyDistributionRow, decodeSenderKeyRecord, decodeStoreCount, encodeSenderKeyRecord, encodeSignalSessionRecord, toSignalAddressParts } from './encoding.js';
+export { decodeStoreCount, toSignalAddressParts } from './encoding.js';
+export { decodeSignalRemoteIdentity, decodeSignalSessionRecord, encodeSignalSessionRecord } from './session/encoding.js';
+export { decodeSignalPreKeyRow, decodeSignalRegistrationRow, decodeSignalSignedPreKeyRow } from './registration/encoding.js';
+export { decodeSenderKeyDistributionRow, decodeSenderKeyRecord, encodeSenderKeyRecord } from './group/encoding.js';
 export { generatePreKeyPair, generateRegistrationId, generateRegistrationInfo, generateSignedPreKey } from './registration/keygen.js';
 export { buildPreKeyUploadIq, parsePreKeyUploadFailure } from './api/prekeys.js';
 export { SignalDigestSyncApi } from './api/SignalDigestSyncApi.js';

package/dist/esm/signal/registration/encoding.js

@@ -0,0 +1,34 @@
+import { asBytes, asNumber, toBoolOrUndef } from '../../util/coercion.js';
+/** Decodes a stored signal-registration SQL row into a {@link RegistrationInfo}. */
+export function decodeSignalRegistrationRow(row) {
+    return {
+        registrationId: asNumber(row.registration_id, 'signal_registration.registration_id'),
+        identityKeyPair: {
+            pubKey: asBytes(row.identity_pub_key, 'signal_registration.identity_pub_key'),
+            privKey: asBytes(row.identity_priv_key, 'signal_registration.identity_priv_key')
+        }
+    };
+}
+/** Decodes a one-time prekey SQL row into a {@link PreKeyRecord}. */
+export function decodeSignalPreKeyRow(row) {
+    return {
+        keyId: asNumber(row.key_id, 'signal_prekey.key_id'),
+        keyPair: {
+            pubKey: asBytes(row.pub_key, 'signal_prekey.pub_key'),
+            privKey: asBytes(row.priv_key, 'signal_prekey.priv_key')
+        },
+        uploaded: toBoolOrUndef(row.uploaded)
+    };
+}
+/** Decodes a signed-prekey SQL row into a {@link SignedPreKeyRecord}. */
+export function decodeSignalSignedPreKeyRow(row) {
+    return {
+        keyId: asNumber(row.key_id, 'signal_signed_prekey.key_id'),
+        keyPair: {
+            pubKey: asBytes(row.pub_key, 'signal_signed_prekey.pub_key'),
+            privKey: asBytes(row.priv_key, 'signal_signed_prekey.priv_key')
+        },
+        signature: asBytes(row.signature, 'signal_signed_prekey.signature'),
+        uploaded: toBoolOrUndef(row.uploaded)
+    };
+}

package/dist/esm/signal/registration/keygen.js

@@ -1,7 +1,10 @@
-import { randomIntAsync } from '../../crypto/index.js';
+import { randomIntAsync, xeddsaSign } from '../../crypto/index.js';
 import { toSerializedPubKey } from '../../crypto/core/keys.js';
 import { X25519 } from '../../crypto/curves/X25519.js';
-import { signSignalMessage } from '../crypto/WaAdvSignature.js';
+/**
+ * Generates the per-device Signal registration info – a random registration id
+ * plus a fresh identity X25519 key pair.
+ */
 export async function generateRegistrationInfo() {
     const [registrationId, identityKeyPair] = await Promise.all([
         generateRegistrationId(),
@@ -12,6 +15,7 @@ export async function generateRegistrationInfo() {
         identityKeyPair
     };
 }
+/** Generates a fresh one-time prekey record with the given `keyId`. */
 export async function generatePreKeyPair(keyId) {
     return {
         keyId,
@@ -19,10 +23,14 @@ export async function generatePreKeyPair(keyId) {
         uploaded: false
     };
 }
+/**
+ * Generates a signed prekey: a fresh X25519 keypair plus an XEdDSA signature
+ * over its serialized public key, signed by `signingPrivateKey` (identity key).
+ */
 export async function generateSignedPreKey(keyId, signingPrivateKey) {
     const keyPair = await X25519.generateKeyPair();
     const serializedPubKey = toSerializedPubKey(keyPair.pubKey);
-    const signature = await signSignalMessage(signingPrivateKey, serializedPubKey);
+    const signature = await xeddsaSign(signingPrivateKey, serializedPubKey);
     return {
         keyId,
         keyPair,
@@ -30,6 +38,7 @@ export async function generateSignedPreKey(keyId, signingPrivateKey) {
         uploaded: false
     };
 }
+/** Generates a Signal registration id in the valid `[1, 16380]` range. */
 export async function generateRegistrationId() {
     return await randomIntAsync(1, 16381);
 }

package/dist/esm/signal/registration/utils.js

@@ -1,5 +1,10 @@
 import { generatePreKeyPair, generateRegistrationInfo, generateSignedPreKey } from '../registration/keygen.js';
-export async function createAndStoreInitialKeys(store) {
+/**
+ * Bootstraps a fresh Signal identity: generates registration info, the first
+ * signed prekey, and the first one-time prekey, then persists them in order
+ * so a partial commit can never split bootstrap state.
+ */
+export async function createAndStoreInitialKeys(store, preKeyStore) {
     const [registrationInfo, firstPreKey] = await Promise.all([
         generateRegistrationInfo(),
         generatePreKeyPair(1)
@@ -8,7 +13,8 @@ export async function createAndStoreInitialKeys(store) {
     // Keep writes ordered so partial commit failures don't leave split registration bootstrap state.
     await store.setRegistrationInfo(registrationInfo);
     await store.setSignedPreKey(signedPreKey);
-    await store.getOrGenSinglePreKey(async () => firstPreKey);
+    // eslint-disable-next-line @typescript-eslint/require-await
+    await preKeyStore.getOrGenSinglePreKey(async () => firstPreKey);
     return {
         registrationInfo,
         signedPreKey,

package/dist/esm/signal/session/SignalProtocol.js

@@ -1,27 +1,38 @@
 import { toSerializedPubKey } from '../../crypto/index.js';
 import { ConsoleLogger } from '../../infra/log/ConsoleLogger.js';
 import { StoreLock } from '../../infra/perf/StoreLock.js';
+import { signalAddressKey } from '../../protocol/jid.js';
 import { MAX_PREV_SESSIONS } from '../constants.js';
+import { encodeSignalSessionSnapshot } from '../session/encoding.js';
 import { decryptMsg, decryptMsgFromSession, encryptMsg } from '../session/SignalRatchet.js';
 import { deserializeMsg, deserializePkMsg, requirePreKey, requireSignedPreKey } from '../session/SignalSerializer.js';
-import { detachSession, findMatchingSession, generateSerializedKeyPair, initiateSessionIncoming, initiateSessionOutgoing, requireLocalIdentity, toSerializedKeyPair } from '../session/SignalSession.js';
+import { findMatchingSession, generateSerializedKeyPair, initiateSessionIncoming, initiateSessionOutgoing, requireLocalIdentity, toSerializedKeyPair } from '../session/SignalSession.js';
 import { uint8Equal } from '../../util/bytes.js';
-function signalAddressMapKey(address) {
-    return `${address.user}\u0001${address.server ?? ''}\u0001${address.device}`;
-}
 function signalAddressLockKey(address) {
-    return `signal:${signalAddressMapKey(address)}`;
+    return `signal:${signalAddressKey(address)}`;
 }
+/**
+ * High-level Signal protocol session orchestrator: establishes outgoing
+ * sessions from prekey bundles, encrypts/decrypts ratchet messages, and owns
+ * the per-address session mutation lock.
+ */
 export class SignalProtocol {
-    constructor(store, logger = new ConsoleLogger('info')) {
-        this.store = store;
+    constructor(stores, logger = new ConsoleLogger('info')) {
+        this.stores = stores;
         this.logger = logger;
         this.sessionMutationLock = new StoreLock();
     }
+    /**
+     * Builds an outgoing Signal session against a remote prekey bundle. Set
+     * `options.reuseExisting` to skip the handshake when a session already
+     * exists for the same remote identity. Set `options.knownAbsent` only
+     * when the caller already proved (within the same logical step) that no
+     * session exists; it skips the in-lock recheck and forces a new handshake.
+     */
     async establishOutgoingSession(address, remoteBundle, options = {}) {
         return this.runWithAddressLock(address, async () => {
-            if (options.reuseExisting) {
-                const existing = await this.store.getSession(address);
+            if (options.reuseExisting && !options.knownAbsent) {
+                const existing = await this.stores.session.getSession(address);
                 if (existing) {
                     const remoteIdentity = toSerializedPubKey(remoteBundle.identity);
                     if (!uint8Equal(existing.remote.pubKey, remoteIdentity)) {
@@ -31,22 +42,110 @@ export class SignalProtocol {
                 }
             }
             const [local, localOneTimeBase] = await Promise.all([
-                requireLocalIdentity(this.store),
+                requireLocalIdentity(this.stores.signal),
                 generateSerializedKeyPair()
             ]);
             const session = await initiateSessionOutgoing(local, remoteBundle, localOneTimeBase);
             // Keep writes ordered: a stored session without matching remote identity causes false mismatch checks.
-            await this.store.setRemoteIdentity(address, session.remote.pubKey);
-            await this.store.setSession(address, session);
+            await this.stores.identity.setRemoteIdentity(address, session.remote.pubKey);
+            await this.stores.session.setSession(address, session);
             return session;
         });
     }
+    /**
+     * Compute an outgoing session under the per-address lock without
+     * persisting. Caller batches results and persists via
+     * {@link persistOutgoingSessionsBatch} to collapse N `setRemoteIdentity`
+     * + `setSession` round-trips into one bulk write per store.
+     */
+    async prepareOutgoingSession(address, remoteBundle, options = {}) {
+        return this.runWithAddressLock(address, async () => {
+            if (options.reuseExisting && !options.knownAbsent) {
+                const existing = await this.stores.session.getSession(address);
+                if (existing) {
+                    const remoteIdentity = toSerializedPubKey(remoteBundle.identity);
+                    if (!uint8Equal(existing.remote.pubKey, remoteIdentity)) {
+                        throw new Error('identity mismatch');
+                    }
+                    return {
+                        session: existing,
+                        remoteIdentity: existing.remote.pubKey,
+                        reusedExisting: true
+                    };
+                }
+            }
+            const [local, localOneTimeBase] = await Promise.all([
+                requireLocalIdentity(this.stores.signal),
+                generateSerializedKeyPair()
+            ]);
+            const session = await initiateSessionOutgoing(local, remoteBundle, localOneTimeBase);
+            return {
+                session,
+                remoteIdentity: session.remote.pubKey,
+                reusedExisting: false
+            };
+        });
+    }
+    /**
+     * Persist prepared outgoing sessions while holding every per-address
+     * lock (same discipline as {@link encryptMessagesBatch}). Re-reads
+     * sessions inside the lock; defers to a concurrent writer's session
+     * when identities agree to avoid clobbering a fresher ratchet advance,
+     * and reports identity conflicts via `skipped`.
+     */
+    async persistOutgoingSessionsBatch(entries) {
+        if (entries.length === 0)
+            return { resolved: [], skipped: [] };
+        const lockKeys = new Array(entries.length);
+        for (let i = 0; i < entries.length; i += 1) {
+            lockKeys[i] = signalAddressLockKey(entries[i].address);
+        }
+        return this.sessionMutationLock.runMany(lockKeys, async () => {
+            const addresses = entries.map((e) => e.address);
+            const existingSessions = await this.stores.session.getSessionsBatch(addresses);
+            const identityUpdates = [];
+            const sessionUpdates = [];
+            const resolved = [];
+            const skipped = [];
+            for (let i = 0; i < entries.length; i += 1) {
+                const entry = entries[i];
+                const existing = existingSessions[i];
+                if (existing) {
+                    if (uint8Equal(existing.remote.pubKey, entry.remoteIdentity)) {
+                        resolved.push({ address: entry.address, session: existing });
+                        continue;
+                    }
+                    skipped.push({ address: entry.address, reason: 'identity-mismatch' });
+                    continue;
+                }
+                identityUpdates.push({
+                    address: entry.address,
+                    identityKey: entry.remoteIdentity
+                });
+                sessionUpdates.push({ address: entry.address, session: entry.session });
+                resolved.push({ address: entry.address, session: entry.session });
+            }
+            if (identityUpdates.length > 0) {
+                await this.stores.identity.setRemoteIdentities(identityUpdates);
+            }
+            if (sessionUpdates.length > 0) {
+                await this.stores.session.setSessionsBatch(sessionUpdates);
+            }
+            return { resolved, skipped };
+        });
+    }
+    /**
+     * Encrypts `plaintext` for `address`. Returns `pkmsg` when this is the
+     * first message of the session, `msg` otherwise. `expectedIdentity`
+     * enforces identity continuity.
+     */
     async encryptMessage(address, plaintext, expectedIdentity) {
         const [encrypted] = await this.encryptMessagesBatch([
             { address, plaintext, expectedIdentity }
         ]);
         return encrypted;
     }
+    /** Batch variant of {@link encryptMessage} that shares per-address locks. */
     async encryptMessagesBatch(requests, prefetchedSessions) {
         if (requests.length === 0) {
             return [];
@@ -60,7 +159,7 @@ export class SignalProtocol {
             if (prefetchedSessions && prefetchedSessions.length > 0) {
                 for (let index = 0; index < prefetchedSessions.length; index += 1) {
                     const entry = prefetchedSessions[index];
-                    prefetchedByAddress.set(signalAddressMapKey(entry.address), entry.session);
+                    prefetchedByAddress.set(signalAddressKey(entry.address), entry.session);
                 }
             }
             const uniqueAddressKeys = new Array(requests.length);
@@ -68,7 +167,7 @@ export class SignalProtocol {
             let uniqueAddressCount = 0;
             for (let index = 0; index < requests.length; index += 1) {
                 const address = requests[index].address;
-                const addressKey = signalAddressMapKey(address);
+                const addressKey = signalAddressKey(address);
                 let isDuplicate = false;
                 for (let dedupIndex = 0; dedupIndex < uniqueAddressCount; dedupIndex += 1) {
                     if (uniqueAddressKeys[dedupIndex] === addressKey) {
@@ -85,7 +184,7 @@ export class SignalProtocol {
             }
             uniqueAddressKeys.length = uniqueAddressCount;
             uniqueAddresses.length = uniqueAddressCount;
-            const currentSessions = await this.store.getSessionsBatch(uniqueAddresses);
+            const currentSessions = await this.stores.session.getSessionsBatch(uniqueAddresses);
             const latestSessionByAddress = new Map();
             for (let index = 0; index < uniqueAddressCount; index += 1) {
                 const addressKey = uniqueAddressKeys[index];
@@ -105,7 +204,7 @@ export class SignalProtocol {
             for (let index = 0; index < requests.length; index += 1) {
                 const request = requests[index];
                 const address = request.address;
-                const addressKey = signalAddressMapKey(address);
+                const addressKey = signalAddressKey(address);
                 const session = latestSessionByAddress.get(addressKey);
                 if (!session) {
                     throw new Error('signal session not found');
@@ -139,7 +238,7 @@ export class SignalProtocol {
                     identityUpdates[identityIndex] = update;
                     identityIndex += 1;
                 }
-                await this.store.setRemoteIdentities(identityUpdates);
+                await this.stores.identity.setRemoteIdentities(identityUpdates);
             }
             const sessionUpdates = new Array(sessionUpdatesByAddress.size);
             let sessionIndex = 0;
@@ -147,13 +246,17 @@ export class SignalProtocol {
                 sessionUpdates[sessionIndex] = update;
                 sessionIndex += 1;
             }
-            await this.store.setSessionsBatch(sessionUpdates);
+            await this.stores.session.setSessionsBatch(sessionUpdates);
             return results;
         });
     }
+    /**
+     * Decrypts a Signal message (`msg` or `pkmsg`) from `address`. For
+     * `pkmsg`, instantiates the session from the embedded bundle when needed.
+     */
     async decryptMessage(address, envelope) {
         return this.runWithAddressLock(address, async () => {
-            const currentSession = await this.store.getSession(address);
+            const currentSession = await this.stores.session.getSession(address);
             let outcome;
             if (envelope.type === 'pkmsg') {
                 const parsedPk = deserializePkMsg(envelope.ciphertext);
@@ -172,9 +275,9 @@ export class SignalProtocol {
             const identityChanged = !currentSession || !uint8Equal(currentSession.remote.pubKey, nextRemoteIdentity);
             // Keep writes ordered for consistency with resolver identity checks.
             if (identityChanged) {
-                await this.store.setRemoteIdentity(address, nextRemoteIdentity);
+                await this.stores.identity.setRemoteIdentity(address, nextRemoteIdentity);
             }
-            await this.store.setSession(address, outcome.updatedSession);
+            await this.stores.session.setSession(address, outcome.updatedSession);
             return outcome.plaintext;
         });
     }
@@ -192,11 +295,11 @@ export class SignalProtocol {
             };
         }
         const [local, signedPreKey, oneTimePreKey] = await Promise.all([
-            requireLocalIdentity(this.store),
-            requireSignedPreKey(this.store, parsed.localSignedPreKeyId),
+            requireLocalIdentity(this.stores.signal),
+            requireSignedPreKey(this.stores.signal, parsed.localSignedPreKeyId),
             parsed.localOneTimeKeyId === null || parsed.localOneTimeKeyId === undefined
                 ? Promise.resolve(null)
-                : requirePreKey(this.store, parsed.localOneTimeKeyId)
+                : requirePreKey(this.stores.preKey, parsed.localOneTimeKeyId)
         ]);
         const incoming = await initiateSessionIncoming(local, parsed.remote, parsed.sessionBaseKey, {
             signed: toSerializedKeyPair(signedPreKey.keyPair),
@@ -210,7 +313,7 @@ export class SignalProtocol {
             ? {
                 ...incoming,
                 prevSessions: [
-                    detachSession(currentSession),
+                    encodeSignalSessionSnapshot(currentSession),
                     ...currentSession.prevSessions.slice(0, MAX_PREV_SESSIONS - 1)
                 ]
             }
@@ -218,7 +321,7 @@ export class SignalProtocol {
         const [updatedSession, plaintext] = await decryptMsgFromSession(baseSession, parsed);
         // Only consume one-time prekeys after successful decrypt/session materialization.
         if (parsed.localOneTimeKeyId !== null && parsed.localOneTimeKeyId !== undefined) {
-            await this.store.consumePreKeyById(parsed.localOneTimeKeyId);
+            await this.stores.preKey.consumePreKeyById(parsed.localOneTimeKeyId);
         }
         return {
             updatedSession,