zapo-js 0.2.0 → 1.0.0

package/dist/esm/signal/api/SignalMissingPreKeysSyncApi.js

@@ -1,14 +1,18 @@
 import { WA_DEFAULTS, WA_NODE_TAGS } from '../../protocol/constants.js';
 import { splitJid, toUserJid } from '../../protocol/jid.js';
-import { decodeExactLength, parseUint } from '../api/codec.js';
-import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../api/constants.js';
+import { decodeExactLength, parseSignalKeyBundleFromNode, parseUint } from '../api/codec.js';
+import { SIGNAL_REGISTRATION_ID_LENGTH } from '../api/constants.js';
 import { buildMissingPreKeysFetchIq } from '../api/prekeys.js';
 import { registerParsedResultByRawAndCanonicalKey } from '../api/result-map.js';
-import { decodeNodeContentBase64OrBytes, findNodeChildrenByTags, findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
+import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
 function isMissingPreKeysUserResultPreferred(result) {
     return 'devices' in result;
 }
+/**
+ * Fetches missing prekey bundles for specific (user, device, registration id)
+ * triples – used during message encryption when a Signal session is missing.
+ */
 export class SignalMissingPreKeysSyncApi {
     constructor(options) {
         this.logger = options.logger;
@@ -16,6 +20,10 @@ export class SignalMissingPreKeysSyncApi {
         this.defaultTimeoutMs =
             options.defaultTimeoutMs ?? WA_DEFAULTS.SIGNAL_FETCH_KEY_BUNDLES_TIMEOUT_MS;
     }
+    /**
+     * Fetches prekey bundles for the requested `targets` in a single IQ.
+     * Returns either a per-device bundle list or an error envelope per user.
+     */
     async fetchMissingPreKeys(targets, timeoutMs = this.defaultTimeoutMs) {
         if (targets.length === 0) {
             return [];
@@ -91,69 +99,22 @@ export class SignalMissingPreKeysSyncApi {
             if (!Number.isSafeInteger(deviceId) || deviceId < 0) {
                 throw new Error(`missing prekeys device[${index}].id is invalid`);
             }
-            const [registrationNode, identityNode, signedKeyNode, oneTimeNode, deviceIdentityNode] = findNodeChildrenByTags(deviceNode, [
-                WA_NODE_TAGS.REGISTRATION,
-                WA_NODE_TAGS.IDENTITY,
-                WA_NODE_TAGS.SKEY,
-                WA_NODE_TAGS.KEY,
-                WA_NODE_TAGS.DEVICE_IDENTITY
-            ]);
-            if (!registrationNode || !identityNode || !signedKeyNode) {
+            const registrationNode = findNodeChild(deviceNode, WA_NODE_TAGS.REGISTRATION);
+            if (!registrationNode) {
                 throw new Error(`missing prekeys device payload is incomplete for ${userJid}`);
             }
-            const [signedKeyIdNode, signedKeyValueNode, signedKeySignatureNode] = findNodeChildrenByTags(signedKeyNode, [
-                WA_NODE_TAGS.ID,
-                WA_NODE_TAGS.VALUE,
-                WA_NODE_TAGS.SIGNATURE
-            ]);
-            if (!signedKeyIdNode || !signedKeyValueNode || !signedKeySignatureNode) {
-                throw new Error(`missing prekeys signed pre-key is incomplete for ${userJid}`);
-            }
-            let oneTimeIdNode;
-            let oneTimeValueNode;
-            if (oneTimeNode) {
-                const oneTimeNodes = findNodeChildrenByTags(oneTimeNode, [
-                    WA_NODE_TAGS.ID,
-                    WA_NODE_TAGS.VALUE
-                ]);
-                oneTimeIdNode = oneTimeNodes[0];
-                oneTimeValueNode = oneTimeNodes[1];
-            }
-            if (oneTimeNode && (!oneTimeIdNode || !oneTimeValueNode)) {
-                throw new Error(`missing prekeys one-time key is incomplete for ${userJid}`);
-            }
-            const baseBundle = {
-                regId: parseUint(decodeExactLength(registrationNode.content, 'missing prekeys device registration', SIGNAL_REGISTRATION_ID_LENGTH), 'missing prekeys device registration'),
-                identity: decodeExactLength(identityNode.content, 'missing prekeys device identity', SIGNAL_KEY_DATA_LENGTH),
-                signedKey: {
-                    id: parseUint(decodeExactLength(signedKeyIdNode.content, 'missing prekeys device skey.id', SIGNAL_KEY_ID_LENGTH), 'missing prekeys device skey.id'),
-                    publicKey: decodeExactLength(signedKeyValueNode.content, 'missing prekeys device skey.value', SIGNAL_KEY_DATA_LENGTH),
-                    signature: decodeExactLength(signedKeySignatureNode.content, 'missing prekeys device skey.signature', SIGNAL_SIGNATURE_LENGTH)
-                }
+            const regId = parseUint(decodeExactLength(registrationNode.content, 'missing prekeys device registration', SIGNAL_REGISTRATION_ID_LENGTH), 'missing prekeys device registration');
+            const parsed = parseSignalKeyBundleFromNode(deviceNode, 'missing prekeys device');
+            const bundle = {
+                regId,
+                identity: parsed.identity,
+                signedKey: parsed.signedKey,
+                ...(parsed.oneTimeKey ? { oneTimeKey: parsed.oneTimeKey } : {})
             };
-            const bundle = oneTimeIdNode && oneTimeValueNode
-                ? {
-                    ...baseBundle,
-                    oneTimeKey: {
-                        id: parseUint(decodeExactLength(oneTimeIdNode.content, 'missing prekeys device key.id', SIGNAL_KEY_ID_LENGTH), 'missing prekeys device key.id'),
-                        publicKey: decodeExactLength(oneTimeValueNode.content, 'missing prekeys device key.value', SIGNAL_KEY_DATA_LENGTH)
-                    }
-                }
-                : baseBundle;
-            let deviceIdentity;
-            if (deviceIdentityNode) {
-                deviceIdentity = decodeNodeContentBase64OrBytes(deviceIdentityNode.content, 'missing prekeys device device-identity');
-            }
-            bundles[index] = deviceIdentity
-                ? {
-                    deviceJid: deviceId === 0 ? userJid : `${user}:${deviceId}@${server}`,
-                    bundle,
-                    deviceIdentity
-                }
-                : {
-                    deviceJid: deviceId === 0 ? userJid : `${user}:${deviceId}@${server}`,
-                    bundle
-                };
+            const deviceJid = deviceId === 0 ? userJid : `${user}:${deviceId}@${server}`;
+            bundles[index] = parsed.deviceIdentity
+                ? { deviceJid, bundle, deviceIdentity: parsed.deviceIdentity }
+                : { deviceJid, bundle };
         }
         return bundles;
     }

package/dist/esm/signal/api/SignalRotateKeyApi.js

@@ -2,6 +2,11 @@ import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS } from '../../protocol/constants
 import { buildSignedPreKeyRotateIq } from '../api/prekeys.js';
 import { generateSignedPreKey } from '../registration/keygen.js';
 import { parseIqError } from '../../transport/node/query.js';
+/**
+ * Generates a fresh signed prekey and uploads it to the server. Handles the
+ * `406`/`409`/`5xx` error codes by signaling whether a digest re-validation
+ * is required.
+ */
 export class SignalRotateKeyApi {
     constructor(options) {
         this.logger = options.logger;
@@ -9,6 +14,11 @@ export class SignalRotateKeyApi {
         this.signalStore = options.signalStore;
         this.defaultTimeoutMs = options.defaultTimeoutMs ?? WA_DEFAULTS.IQ_TIMEOUT_MS;
     }
+    /**
+     * Rotates the signed prekey by generating a new one (next key id) and
+     * uploading it. Returns `shouldDigestKey: true` when the caller should
+     * re-run a digest validation after the rotation.
+     */
     async rotateSignedPreKey(timeoutMs = this.defaultTimeoutMs) {
         const [registrationInfo, currentSignedPreKey] = await Promise.all([
             this.signalStore.getRegistrationInfo(),

package/dist/esm/signal/api/SignalSessionSyncApi.js

@@ -1,13 +1,18 @@
 import { WA_DEFAULTS, WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from '../../protocol/constants.js';
 import { canonicalizeSignalJid } from '../../protocol/jid.js';
-import { decodeExactLength, parseUint } from '../api/codec.js';
-import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../api/constants.js';
+import { decodeExactLength, parseSignalKeyBundleFromNode, parseUint } from '../api/codec.js';
+import { SIGNAL_REGISTRATION_ID_LENGTH } from '../api/constants.js';
 import { registerParsedResultByRawAndCanonicalKey } from '../api/result-map.js';
-import { findNodeChild, getNodeChildrenByTag, decodeNodeContentBase64OrBytes } from '../../transport/node/helpers.js';
+import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
 import { assertIqResult } from '../../transport/node/query.js';
 function isKeyBundleResultPreferred(result) {
     return 'bundle' in result;
 }
+/**
+ * Fetches per-device prekey bundles required to start a Signal session.
+ * Use {@link fetchKeyBundle} for single-JID calls or {@link fetchKeyBundles}
+ * for batched encryption.
+ */
 export class SignalSessionSyncApi {
     constructor(options) {
         this.logger = options.logger;
@@ -16,6 +21,10 @@ export class SignalSessionSyncApi {
             options.defaultTimeoutMs ?? WA_DEFAULTS.SIGNAL_FETCH_KEY_BUNDLES_TIMEOUT_MS;
         this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
     }
+    /**
+     * Convenience wrapper for {@link fetchKeyBundles} that fetches a single
+     * bundle and throws on server error envelopes.
+     */
     async fetchKeyBundle(target, timeoutMs = this.defaultTimeoutMs) {
         const results = await this.fetchKeyBundles([target], timeoutMs);
         const first = results[0];
@@ -33,6 +42,10 @@ export class SignalSessionSyncApi {
         });
         return parsed;
     }
+    /**
+     * Batched key-bundle fetch. Returns one entry per JID – either a bundle
+     * (success) or an error envelope. Duplicate JIDs are coalesced.
+     */
     async fetchKeyBundles(targets, timeoutMs = this.defaultTimeoutMs) {
         if (targets.length === 0) {
             return [];
@@ -133,57 +146,16 @@ export class SignalSessionSyncApi {
         if (!registrationNode) {
             throw new Error('key bundle user missing registration node');
         }
-        const identityNode = findNodeChild(node, WA_NODE_TAGS.IDENTITY);
-        if (!identityNode) {
-            throw new Error('key bundle user missing identity node');
-        }
-        const signedPreKeyNode = findNodeChild(node, WA_NODE_TAGS.SKEY);
-        if (!signedPreKeyNode) {
-            throw new Error('key bundle user missing signed pre-key node');
-        }
-        const registrationBytes = decodeExactLength(registrationNode.content, 'key bundle registration', SIGNAL_REGISTRATION_ID_LENGTH);
-        const registrationId = parseUint(registrationBytes, 'key bundle registration');
-        const identity = decodeExactLength(identityNode.content, 'key bundle identity', SIGNAL_KEY_DATA_LENGTH);
-        const signedIdNode = findNodeChild(signedPreKeyNode, WA_NODE_TAGS.ID);
-        const signedValueNode = findNodeChild(signedPreKeyNode, WA_NODE_TAGS.VALUE);
-        const signedSignatureNode = findNodeChild(signedPreKeyNode, WA_NODE_TAGS.SIGNATURE);
-        if (!signedIdNode || !signedValueNode || !signedSignatureNode) {
-            throw new Error('key bundle signed pre-key is incomplete');
-        }
-        const signedIdBytes = decodeExactLength(signedIdNode.content, 'key bundle skey.id', SIGNAL_KEY_ID_LENGTH);
-        const signedValue = decodeExactLength(signedValueNode.content, 'key bundle skey.value', SIGNAL_KEY_DATA_LENGTH);
-        const signedSignature = decodeExactLength(signedSignatureNode.content, 'key bundle skey.signature', SIGNAL_SIGNATURE_LENGTH);
-        const preKeyNode = findNodeChild(node, WA_NODE_TAGS.KEY);
-        let oneTimeKey;
-        if (preKeyNode) {
-            const preKeyIdNode = findNodeChild(preKeyNode, WA_NODE_TAGS.ID);
-            const preKeyValueNode = findNodeChild(preKeyNode, WA_NODE_TAGS.VALUE);
-            if (!preKeyIdNode || !preKeyValueNode) {
-                throw new Error('key bundle one-time pre-key is incomplete');
-            }
-            const preKeyIdBytes = decodeExactLength(preKeyIdNode.content, 'key bundle key.id', SIGNAL_KEY_ID_LENGTH);
-            const preKeyValue = decodeExactLength(preKeyValueNode.content, 'key bundle key.value', SIGNAL_KEY_DATA_LENGTH);
-            oneTimeKey = {
-                id: parseUint(preKeyIdBytes, 'key bundle key.id'),
-                publicKey: preKeyValue
-            };
-        }
-        const deviceIdentityNode = findNodeChild(node, WA_NODE_TAGS.DEVICE_IDENTITY);
-        const deviceIdentity = deviceIdentityNode
-            ? decodeNodeContentBase64OrBytes(deviceIdentityNode.content, 'key bundle device-identity')
-            : undefined;
+        const regId = parseUint(decodeExactLength(registrationNode.content, 'key bundle registration', SIGNAL_REGISTRATION_ID_LENGTH), 'key bundle registration');
+        const parsed = parseSignalKeyBundleFromNode(node, 'key bundle');
         return {
             bundle: {
-                regId: registrationId,
-                identity,
-                signedKey: {
-                    id: parseUint(signedIdBytes, 'key bundle skey.id'),
-                    publicKey: signedValue,
-                    signature: signedSignature
-                },
-                ...(oneTimeKey ? { oneTimeKey } : {})
+                regId,
+                identity: parsed.identity,
+                signedKey: parsed.signedKey,
+                ...(parsed.oneTimeKey ? { oneTimeKey: parsed.oneTimeKey } : {})
             },
-            ...(deviceIdentity ? { deviceIdentity } : {})
+            ...(parsed.deviceIdentity ? { deviceIdentity: parsed.deviceIdentity } : {})
         };
     }
 }

package/dist/esm/signal/api/codec.js

@@ -1,4 +1,6 @@
-import { decodeNodeContentBase64OrBytes } from '../../transport/node/helpers.js';
+import { WA_NODE_TAGS } from '../../protocol/constants.js';
+import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../api/constants.js';
+import { decodeNodeContentBase64OrBytes, findNodeChildrenByTags } from '../../transport/node/helpers.js';
 export function decodeExactLength(value, field, expectedLength) {
     const bytes = decodeNodeContentBase64OrBytes(value, field);
     if (bytes.byteLength !== expectedLength) {
@@ -21,3 +23,52 @@ export function parseUint(bytes, field) {
     }
     throw new Error(`${field} has invalid byte length`);
 }
+/**
+ * Parses the shared `<identity><skey id|value|signature><key id|value><device-identity>`
+ * shape used by session pre-key bundles, missing pre-key device bundles, and retry
+ * receipt key bundles. Caller is responsible for parsing the `<registration>` node
+ * separately when it lives at the same level (it's omitted from retry bundles).
+ */
+export function parseSignalKeyBundleFromNode(node, fieldPrefix) {
+    const [identityNode, signedKeyNode, oneTimeKeyNode, deviceIdentityNode] = findNodeChildrenByTags(node, [
+        WA_NODE_TAGS.IDENTITY,
+        WA_NODE_TAGS.SKEY,
+        WA_NODE_TAGS.KEY,
+        WA_NODE_TAGS.DEVICE_IDENTITY
+    ]);
+    if (!identityNode) {
+        throw new Error(`${fieldPrefix} missing identity node`);
+    }
+    if (!signedKeyNode) {
+        throw new Error(`${fieldPrefix} missing signed pre-key node`);
+    }
+    const identity = decodeExactLength(identityNode.content, `${fieldPrefix}.identity`, SIGNAL_KEY_DATA_LENGTH);
+    const [signedKeyIdNode, signedKeyValueNode, signedKeySignatureNode] = findNodeChildrenByTags(signedKeyNode, [WA_NODE_TAGS.ID, WA_NODE_TAGS.VALUE, WA_NODE_TAGS.SIGNATURE]);
+    if (!signedKeyIdNode || !signedKeyValueNode || !signedKeySignatureNode) {
+        throw new Error(`${fieldPrefix} signed pre-key is incomplete`);
+    }
+    const signedKey = {
+        id: parseUint(decodeExactLength(signedKeyIdNode.content, `${fieldPrefix}.skey.id`, SIGNAL_KEY_ID_LENGTH), `${fieldPrefix}.skey.id`),
+        publicKey: decodeExactLength(signedKeyValueNode.content, `${fieldPrefix}.skey.value`, SIGNAL_KEY_DATA_LENGTH),
+        signature: decodeExactLength(signedKeySignatureNode.content, `${fieldPrefix}.skey.signature`, SIGNAL_SIGNATURE_LENGTH)
+    };
+    let oneTimeKey;
+    if (oneTimeKeyNode) {
+        const [oneTimeKeyIdNode, oneTimeKeyValueNode] = findNodeChildrenByTags(oneTimeKeyNode, [
+            WA_NODE_TAGS.ID,
+            WA_NODE_TAGS.VALUE
+        ]);
+        if (!oneTimeKeyIdNode || !oneTimeKeyValueNode) {
+            throw new Error(`${fieldPrefix} one-time pre-key is incomplete`);
+        }
+        oneTimeKey = {
+            id: parseUint(decodeExactLength(oneTimeKeyIdNode.content, `${fieldPrefix}.key.id`, SIGNAL_KEY_ID_LENGTH), `${fieldPrefix}.key.id`),
+            publicKey: decodeExactLength(oneTimeKeyValueNode.content, `${fieldPrefix}.key.value`, SIGNAL_KEY_DATA_LENGTH)
+        };
+    }
+    let deviceIdentity;
+    if (deviceIdentityNode) {
+        deviceIdentity = decodeNodeContentBase64OrBytes(deviceIdentityNode.content, `${fieldPrefix}.device-identity`);
+    }
+    return { identity, signedKey, oneTimeKey, deviceIdentity };
+}

package/dist/esm/signal/api/prekeys.js

@@ -1,5 +1,9 @@
 import { parseIqError } from '../../transport/node/query.js';
 export { buildMissingPreKeysFetchIq, buildPreKeyUploadIq, buildSignedPreKeyRotateIq } from '../../transport/node/builders/prekeys.js';
+/**
+ * Extracts the numeric error code and text from a failed `prekey` upload IQ
+ * response. Use after a non-success status to decide whether to retry.
+ */
 export function parsePreKeyUploadFailure(node) {
     const error = parseIqError(node);
     return {

package/dist/esm/signal/attestation/WaAdvSignature.js

@@ -0,0 +1,17 @@
+import { hmacSha256Sign, toRawPubKey, xeddsaSign, xeddsaVerify } from '../../crypto/index.js';
+import { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE, ADV_PREFIX_HOSTED_DEVICE_SIGNATURE } from '../attestation/constants.js';
+import { concatBytes } from '../../util/bytes.js';
+export { ADV_PREFIX_ACCOUNT_SIGNATURE, ADV_PREFIX_DEVICE_SIGNATURE, ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE } from '../attestation/constants.js';
+export async function verifyDeviceIdentityAccountSignature(details, accountSignature, identityPublicKey, accountSignatureKey, isHosted = false) {
+    const prefix = isHosted ? ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE : ADV_PREFIX_ACCOUNT_SIGNATURE;
+    const message = concatBytes([prefix, details, identityPublicKey]);
+    return xeddsaVerify(toRawPubKey(accountSignatureKey), message, accountSignature);
+}
+export async function generateDeviceSignature(details, identityKeyPair, accountSignatureKey, isHosted = false) {
+    const prefix = isHosted ? ADV_PREFIX_HOSTED_DEVICE_SIGNATURE : ADV_PREFIX_DEVICE_SIGNATURE;
+    const message = concatBytes([prefix, details, identityKeyPair.pubKey, accountSignatureKey]);
+    return xeddsaSign(identityKeyPair.privKey, message);
+}
+export function computeAdvIdentityHmac(secretKey, details) {
+    return hmacSha256Sign(secretKey, details);
+}

package/dist/esm/signal/{crypto → attestation}/constants.js

@@ -1,7 +1,3 @@
-export const SIGNAL_PREFIX_SIGNATURE_RANDOM = new Uint8Array([
-    0xfe, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
-    0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
-]);
 export const ADV_PREFIX_ACCOUNT_SIGNATURE = new Uint8Array([6, 0]);
 export const ADV_PREFIX_DEVICE_SIGNATURE = new Uint8Array([6, 1]);
 export const ADV_PREFIX_HOSTED_ACCOUNT_SIGNATURE = new Uint8Array([6, 5]);

package/dist/esm/signal/constants.js

@@ -9,4 +9,7 @@ export const SENDER_KEY_FUTURE_MESSAGES_MAX = 20000;
 export const MESSAGE_KEY_LABEL = new Uint8Array([1]);
 export const CHAIN_KEY_LABEL = new Uint8Array([2]);
 export const WHISPER_GROUP_INFO = TEXT_ENCODER.encode('WhisperGroup');
+export const WHISPER_MESSAGE_KEYS_INFO = TEXT_ENCODER.encode('WhisperMessageKeys');
+export const WHISPER_TEXT_INFO = TEXT_ENCODER.encode('WhisperText');
+export const WHISPER_RATCHET_INFO = TEXT_ENCODER.encode('WhisperRatchet');
 export const SIGNAL_PREFIX = new Uint8Array(32).fill(0xff);