zapo-js 0.1.0

package/dist/esm/retry/parse.js

@@ -0,0 +1,130 @@
+import { WA_MESSAGE_TAGS, WA_NODE_TAGS } from '../protocol/constants.js';
+import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../signal/api/constants.js';
+import { decodeNodeContentBase64OrBytes, findNodeChild } from '../transport/node/helpers.js';
+import { parseOptionalInt } from '../transport/stream/parse.js';
+function parseFixedLengthBytes(value, byteLength, field) {
+    const out = decodeNodeContentBase64OrBytes(value, field);
+    if (out.byteLength !== byteLength) {
+        throw new Error(`${field} must be ${byteLength} bytes`);
+    }
+    return out;
+}
+function parseBigEndianUint(bytes, field) {
+    if (bytes.byteLength === 0 || bytes.byteLength > 4) {
+        throw new Error(`${field} has invalid byte length`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.byteLength === 1) {
+        return view.getUint8(0);
+    }
+    if (bytes.byteLength === 2) {
+        return view.getUint16(0);
+    }
+    return bytes.byteLength === 3 ? (view.getUint16(0) << 8) | view.getUint8(2) : view.getUint32(0);
+}
+function parseRetryType(value) {
+    if (value === 'retry' || value === 'enc_rekey_retry') {
+        return value;
+    }
+    return null;
+}
+function parseRetryCount(value) {
+    const parsed = parseOptionalInt(value);
+    if (parsed === undefined) {
+        return 0;
+    }
+    if (parsed < 0) {
+        throw new Error('retry count must be >= 0');
+    }
+    return parsed;
+}
+function parseRetryReason(value) {
+    const parsed = parseOptionalInt(value);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    if (parsed < 0) {
+        throw new Error('retry reason must be >= 0');
+    }
+    return parsed;
+}
+function parseRetryKeyBundle(node) {
+    if (!node) {
+        return undefined;
+    }
+    const identityNode = findNodeChild(node, WA_NODE_TAGS.IDENTITY);
+    const signedKeyNode = findNodeChild(node, WA_NODE_TAGS.SKEY);
+    if (!identityNode || !signedKeyNode) {
+        throw new Error('retry keys section missing identity or skey');
+    }
+    const signedKeyIdNode = findNodeChild(signedKeyNode, WA_NODE_TAGS.ID);
+    const signedKeyValueNode = findNodeChild(signedKeyNode, WA_NODE_TAGS.VALUE);
+    const signedKeySignatureNode = findNodeChild(signedKeyNode, WA_NODE_TAGS.SIGNATURE);
+    if (!signedKeyIdNode || !signedKeyValueNode || !signedKeySignatureNode) {
+        throw new Error('retry keys section has incomplete skey');
+    }
+    const keyNode = findNodeChild(node, WA_NODE_TAGS.KEY);
+    const keyIdNode = keyNode ? findNodeChild(keyNode, WA_NODE_TAGS.ID) : undefined;
+    const keyValueNode = keyNode ? findNodeChild(keyNode, WA_NODE_TAGS.VALUE) : undefined;
+    if (keyNode && (!keyIdNode || !keyValueNode)) {
+        throw new Error('retry keys section has incomplete key');
+    }
+    const deviceIdentityNode = findNodeChild(node, WA_NODE_TAGS.DEVICE_IDENTITY);
+    return {
+        identity: parseFixedLengthBytes(identityNode.content, SIGNAL_KEY_DATA_LENGTH, 'retry.keys.identity'),
+        deviceIdentity: deviceIdentityNode
+            ? decodeNodeContentBase64OrBytes(deviceIdentityNode.content, 'retry.keys.device-identity')
+            : undefined,
+        key: keyIdNode && keyValueNode
+            ? {
+                id: parseBigEndianUint(parseFixedLengthBytes(keyIdNode.content, SIGNAL_KEY_ID_LENGTH, 'retry.keys.key.id'), 'retry.keys.key.id'),
+                publicKey: parseFixedLengthBytes(keyValueNode.content, SIGNAL_KEY_DATA_LENGTH, 'retry.keys.key.value')
+            }
+            : undefined,
+        skey: {
+            id: parseBigEndianUint(parseFixedLengthBytes(signedKeyIdNode.content, SIGNAL_KEY_ID_LENGTH, 'retry.keys.skey.id'), 'retry.keys.skey.id'),
+            publicKey: parseFixedLengthBytes(signedKeyValueNode.content, SIGNAL_KEY_DATA_LENGTH, 'retry.keys.skey.value'),
+            signature: parseFixedLengthBytes(signedKeySignatureNode.content, SIGNAL_SIGNATURE_LENGTH, 'retry.keys.skey.signature')
+        }
+    };
+}
+export function parseRetryReceiptRequest(node) {
+    if (node.tag !== WA_MESSAGE_TAGS.RECEIPT) {
+        return null;
+    }
+    const receiptType = parseRetryType(node.attrs.type);
+    if (!receiptType) {
+        return null;
+    }
+    const stanzaId = node.attrs.id;
+    const from = node.attrs.from;
+    if (!stanzaId || !from) {
+        throw new Error('retry receipt is missing id/from attrs');
+    }
+    const retryNode = findNodeChild(node, 'retry');
+    if (!retryNode) {
+        throw new Error('retry receipt is missing retry child');
+    }
+    const registrationNode = findNodeChild(node, WA_NODE_TAGS.REGISTRATION);
+    if (!registrationNode) {
+        throw new Error('retry receipt is missing registration child');
+    }
+    const originalMsgId = retryNode.attrs.id;
+    if (!originalMsgId) {
+        throw new Error('retry receipt is missing retry.id');
+    }
+    const registration = parseFixedLengthBytes(registrationNode.content, SIGNAL_REGISTRATION_ID_LENGTH, 'retry.registration');
+    return {
+        type: receiptType,
+        stanzaId,
+        from,
+        participant: node.attrs.participant,
+        recipient: node.attrs.recipient,
+        originalMsgId,
+        retryCount: parseRetryCount(retryNode.attrs.count),
+        retryReason: parseRetryReason(retryNode.attrs.error ?? node.attrs.error),
+        t: retryNode.attrs.t ?? node.attrs.t,
+        regId: parseBigEndianUint(registration, 'retry.registration'),
+        keyBundle: parseRetryKeyBundle(findNodeChild(node, 'keys'))
+    };
+}

package/dist/esm/retry/reason.js

@@ -0,0 +1,50 @@
+import { RETRY_REASON } from './constants.js';
+import { toError } from '../util/primitives.js';
+const RETRY_REASON_MATCHERS = [
+    {
+        matches: ['no session', 'session not found'],
+        code: RETRY_REASON.SignalErrorNoSession
+    },
+    { matches: ['invalid key id'], code: RETRY_REASON.SignalErrorInvalidKeyId },
+    { matches: ['invalid key'], code: RETRY_REASON.SignalErrorInvalidKey },
+    {
+        matches: [
+            'invalid signal message',
+            'invalid prekey signal message',
+            'invalid sender key message'
+        ],
+        code: RETRY_REASON.SignalErrorInvalidMessage
+    },
+    { matches: ['invalid signature'], code: RETRY_REASON.SignalErrorInvalidSignature },
+    {
+        matches: ['too many messages in future', 'future message'],
+        code: RETRY_REASON.SignalErrorFutureMessage
+    },
+    { matches: ['invalid mac'], code: RETRY_REASON.SignalErrorBadMac },
+    { matches: ['invalid session'], code: RETRY_REASON.SignalErrorInvalidSession },
+    { matches: ['invalid message key'], code: RETRY_REASON.SignalErrorInvalidMsgKey },
+    {
+        matches: [['broadcast', 'ephemeral']],
+        code: RETRY_REASON.BadBroadcastEphemeralSetting
+    },
+    {
+        matches: ['unknown companion', 'unknown device'],
+        code: RETRY_REASON.UnknownCompanionNoPrekey
+    },
+    { matches: ['adv'], code: RETRY_REASON.AdvFailure },
+    {
+        matches: [['status', 'revoke', 'delay']],
+        code: RETRY_REASON.StatusRevokeDelay
+    }
+];
+export function mapRetryReasonFromError(error) {
+    const message = toError(error).message.toLowerCase();
+    for (const matcher of RETRY_REASON_MATCHERS) {
+        if (matcher.matches.some((candidate) => Array.isArray(candidate)
+            ? candidate.every((part) => message.includes(part))
+            : message.includes(candidate))) {
+            return matcher.code;
+        }
+    }
+    return RETRY_REASON.UnknownError;
+}

package/dist/esm/retry/replay.js

@@ -0,0 +1,177 @@
+import { wrapDeviceSentMessage } from '../message/device-sent.js';
+import { unpadPkcs7, writeRandomPadMax16 } from '../message/padding.js';
+import { proto } from '../proto.js';
+import { isGroupOrBroadcastJid, normalizeDeviceJid, parseSignalAddressFromJid, splitJid, toUserJid } from '../protocol/jid.js';
+import { decodeRetryReplayPayload } from './outbound.js';
+import { decodeBinaryNode } from '../transport/binary/index.js';
+import { buildGroupRetryMessageNode } from '../transport/node/builders/message.js';
+import { findNodeChild, getNodeChildrenByTag } from '../transport/node/helpers.js';
+import { toError } from '../util/primitives.js';
+export class WaRetryReplayService {
+    constructor(options) {
+        this.options = options;
+    }
+    async resendOutboundMessage(outbound, requesterJid, retryCount) {
+        const payload = decodeRetryReplayPayload(outbound.replayPayload);
+        if (payload.mode === 'plaintext') {
+            return this.resendPlaintextPayload(outbound, payload, requesterJid, retryCount);
+        }
+        if (payload.mode === 'encrypted') {
+            return this.resendEncryptedPayload(outbound, payload, requesterJid, retryCount);
+        }
+        return this.resendOpaquePayload(outbound, payload, requesterJid);
+    }
+    async resendPlaintextPayload(outbound, payload, requesterJid, retryCount) {
+        if (isGroupOrBroadcastJid(payload.to)) {
+            return this.resendGroupPlaintextPayload(outbound, payload, requesterJid);
+        }
+        let payloadUserJid;
+        let requesterUserJid;
+        try {
+            payloadUserJid = toUserJid(payload.to);
+            requesterUserJid = toUserJid(requesterJid);
+        }
+        catch {
+            return 'ineligible';
+        }
+        if (payloadUserJid !== requesterUserJid) {
+            return 'ineligible';
+        }
+        const encrypted = await this.signalProtocol.encryptMessage(parseSignalAddressFromJid(requesterJid), payload.plaintext);
+        await this.messageClient.sendEncrypted({
+            to: requesterJid,
+            encType: encrypted.type,
+            ciphertext: encrypted.ciphertext,
+            encCount: retryCount,
+            id: outbound.messageId,
+            type: payload.type
+        });
+        return 'resent';
+    }
+    async resendGroupPlaintextPayload(outbound, payload, requesterJid) {
+        const plaintext = (await this.maybeWrapGroupRetryPlaintextForSelfDevice(payload, requesterJid)) ??
+            payload.plaintext;
+        const encrypted = await this.signalProtocol.encryptMessage(parseSignalAddressFromJid(requesterJid), plaintext);
+        let deviceIdentity;
+        if (encrypted.type === 'pkmsg') {
+            const signedIdentity = this.getCurrentSignedIdentity();
+            if (!signedIdentity) {
+                this.logger.warn('retry request rejected: missing signed identity for pkmsg group retry');
+                return 'ineligible';
+            }
+            deviceIdentity = proto.ADVSignedDeviceIdentity.encode(signedIdentity).finish();
+        }
+        const retryNode = buildGroupRetryMessageNode({
+            to: payload.to,
+            type: payload.type,
+            id: outbound.messageId,
+            requesterJid,
+            addressingMode: splitJid(requesterJid).server === 'lid' ? 'lid' : 'pn',
+            encType: encrypted.type,
+            ciphertext: encrypted.ciphertext,
+            deviceIdentity
+        });
+        await this.messageClient.sendMessageNode(retryNode);
+        return 'resent';
+    }
+    async resendEncryptedPayload(outbound, payload, requesterJid, retryCount) {
+        if (payload.encType === 'skmsg') {
+            return 'ineligible';
+        }
+        if (normalizeDeviceJid(payload.to) !== normalizeDeviceJid(requesterJid)) {
+            return 'ineligible';
+        }
+        await this.messageClient.sendEncrypted({
+            to: requesterJid,
+            encType: payload.encType,
+            ciphertext: payload.ciphertext,
+            encCount: retryCount,
+            id: outbound.messageId,
+            type: payload.type,
+            participant: payload.participant
+        });
+        return 'resent';
+    }
+    async resendOpaquePayload(outbound, payload, requesterJid) {
+        const decoded = decodeBinaryNode(payload.node);
+        const replayNode = decoded.attrs.id === outbound.messageId
+            ? decoded
+            : {
+                ...decoded,
+                attrs: {
+                    ...decoded.attrs,
+                    id: outbound.messageId
+                }
+            };
+        if (!this.isOpaqueReplayCompatible(replayNode, requesterJid)) {
+            return 'ineligible';
+        }
+        await this.messageClient.sendMessageNode(replayNode);
+        return 'resent';
+    }
+    async maybeWrapGroupRetryPlaintextForSelfDevice(payload, requesterJid) {
+        if (!this.isRequesterCurrentAccount(requesterJid)) {
+            return null;
+        }
+        try {
+            const messageBytes = unpadPkcs7(payload.plaintext);
+            const message = proto.Message.decode(messageBytes);
+            const wrapped = wrapDeviceSentMessage(message, payload.to);
+            return writeRandomPadMax16(proto.Message.encode(wrapped).finish());
+        }
+        catch (error) {
+            this.logger.warn('retry request failed to wrap deviceSent payload for self requester', {
+                requester: requesterJid,
+                to: payload.to,
+                message: toError(error).message
+            });
+            return null;
+        }
+    }
+    isRequesterCurrentAccount(requesterJid) {
+        const requesterUser = toUserJid(requesterJid);
+        const meJid = this.options.getCurrentMeJid();
+        if (meJid && toUserJid(meJid) === requesterUser) {
+            return true;
+        }
+        const meLid = this.options.getCurrentMeLid();
+        if (meLid && toUserJid(meLid) === requesterUser) {
+            return true;
+        }
+        return false;
+    }
+    get logger() {
+        return this.options.logger;
+    }
+    get messageClient() {
+        return this.options.messageClient;
+    }
+    get signalProtocol() {
+        return this.options.signalProtocol;
+    }
+    getCurrentSignedIdentity() {
+        return this.options.getCurrentSignedIdentity();
+    }
+    isOpaqueReplayCompatible(node, requesterJid) {
+        const requester = normalizeDeviceJid(requesterJid);
+        const participantsNode = findNodeChild(node, 'participants');
+        if (participantsNode) {
+            const toNodes = getNodeChildrenByTag(participantsNode, 'to');
+            if (toNodes.length !== 1) {
+                return false;
+            }
+            const participantJid = toNodes[0].attrs.jid;
+            if (!participantJid) {
+                return false;
+            }
+            return normalizeDeviceJid(participantJid) === requester;
+        }
+        if (node.attrs.participant) {
+            return normalizeDeviceJid(node.attrs.participant) === requester;
+        }
+        if (node.attrs.to) {
+            return normalizeDeviceJid(node.attrs.to) === requester;
+        }
+        return false;
+    }
+}

package/dist/esm/retry/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,185 @@
+import { randomInt } from 'node:crypto';
+import { WA_DEFAULTS, WA_NODE_TAGS, WA_XMLNS } from '../../protocol/constants.js';
+import { parseSignalAddressFromJid, splitJid } from '../../protocol/jid.js';
+import { findNodeChild, getNodeChildrenByTag } from '../../transport/node/helpers.js';
+import { assertIqResult, buildIqNode } from '../../transport/node/query.js';
+export class SignalDeviceSyncApi {
+    constructor(options) {
+        this.logger = options.logger;
+        this.query = options.query;
+        this.deviceListStore = options.deviceListStore;
+        this.defaultTimeoutMs =
+            options.defaultTimeoutMs ?? WA_DEFAULTS.SIGNAL_FETCH_KEY_BUNDLES_TIMEOUT_MS;
+        this.hostDomain = options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN;
+    }
+    async syncDeviceList(userJids, timeoutMs = this.defaultTimeoutMs) {
+        const normalizedUsers = this.normalizeUsers(userJids);
+        if (normalizedUsers.length === 0) {
+            return [];
+        }
+        const nowMs = Date.now();
+        const cachedByUser = new Map();
+        const usersToQuery = this.deviceListStore
+            ? await this.collectUsersToQuery(normalizedUsers, nowMs, cachedByUser, this.deviceListStore)
+            : normalizedUsers;
+        if (usersToQuery.length === 0) {
+            return normalizedUsers.map((jid) => ({
+                jid,
+                deviceJids: cachedByUser.get(jid) ?? []
+            }));
+        }
+        const request = this.makeDeviceSyncRequest(usersToQuery);
+        this.logger.debug('signal device sync request', {
+            users: usersToQuery.length,
+            timeoutMs
+        });
+        const response = await this.query(request, timeoutMs);
+        const parsed = this.parseDeviceSyncResponse(response, usersToQuery);
+        if (this.deviceListStore) {
+            const updatedAtMs = Date.now();
+            await this.deviceListStore.upsertUserDevicesBatch(parsed.map((entry) => ({
+                userJid: entry.jid,
+                deviceJids: entry.deviceJids,
+                updatedAtMs
+            })));
+        }
+        const parsedByUser = new Map(parsed.map((entry) => [entry.jid, entry.deviceJids]));
+        const merged = normalizedUsers.map((jid) => ({
+            jid,
+            deviceJids: parsedByUser.get(jid) ?? cachedByUser.get(jid) ?? []
+        }));
+        this.logger.debug('signal device sync success', {
+            users: merged.length,
+            devices: merged.reduce((total, entry) => total + entry.deviceJids.length, 0)
+        });
+        return merged;
+    }
+    async collectUsersToQuery(normalizedUsers, nowMs, cachedByUser, store) {
+        const records = await store.getUserDevicesBatch(normalizedUsers, nowMs);
+        const usersToQuery = [];
+        for (let index = 0; index < normalizedUsers.length; index += 1) {
+            const userJid = normalizedUsers[index];
+            const record = records[index];
+            if (!record) {
+                usersToQuery.push(userJid);
+                continue;
+            }
+            cachedByUser.set(userJid, record.deviceJids);
+        }
+        return usersToQuery;
+    }
+    makeDeviceSyncRequest(userJids) {
+        return buildIqNode('get', this.hostDomain, WA_XMLNS.USYNC, [
+            {
+                tag: WA_NODE_TAGS.USYNC,
+                attrs: {
+                    sid: this.makeSid(),
+                    index: '0',
+                    last: 'true',
+                    mode: WA_NODE_TAGS.QUERY,
+                    context: 'interactive'
+                },
+                content: [
+                    {
+                        tag: WA_NODE_TAGS.QUERY,
+                        attrs: {},
+                        content: [
+                            {
+                                tag: WA_NODE_TAGS.DEVICES,
+                                attrs: {
+                                    version: '2'
+                                }
+                            }
+                        ]
+                    },
+                    {
+                        tag: WA_NODE_TAGS.LIST,
+                        attrs: {},
+                        content: userJids.map((jid) => ({
+                            tag: WA_NODE_TAGS.USER,
+                            attrs: { jid }
+                        }))
+                    }
+                ]
+            }
+        ]);
+    }
+    parseDeviceSyncResponse(node, requestedUsers) {
+        assertIqResult(node, 'signal device sync');
+        const usyncNode = findNodeChild(node, WA_NODE_TAGS.USYNC);
+        if (!usyncNode) {
+            throw new Error('signal device sync response missing usync node');
+        }
+        const listNode = findNodeChild(usyncNode, WA_NODE_TAGS.LIST);
+        if (!listNode) {
+            throw new Error('signal device sync response missing list node');
+        }
+        const requestedSet = new Set(requestedUsers);
+        const userNodes = getNodeChildrenByTag(listNode, WA_NODE_TAGS.USER);
+        return userNodes.flatMap((userNode) => {
+            const userJid = userNode.attrs.jid;
+            if (!userJid) {
+                return [];
+            }
+            const normalizedUserJid = this.normalizeUserJid(userJid);
+            if (!requestedSet.has(normalizedUserJid)) {
+                return [];
+            }
+            return [
+                {
+                    jid: normalizedUserJid,
+                    deviceJids: this.parseUserDeviceJids(userNode, normalizedUserJid)
+                }
+            ];
+        });
+    }
+    parseUserDeviceJids(userNode, userJid) {
+        const devicesNode = findNodeChild(userNode, WA_NODE_TAGS.DEVICES);
+        if (!devicesNode) {
+            return [];
+        }
+        const errorNode = findNodeChild(devicesNode, WA_NODE_TAGS.ERROR);
+        if (errorNode) {
+            this.logger.warn('signal device sync user error', {
+                jid: userJid,
+                code: errorNode.attrs.code,
+                text: errorNode.attrs.text
+            });
+            return [];
+        }
+        const deviceListNode = findNodeChild(devicesNode, 'device-list');
+        if (!deviceListNode) {
+            return [];
+        }
+        return [
+            ...new Set(getNodeChildrenByTag(deviceListNode, 'device')
+                .map((deviceNode) => {
+                const parsedId = deviceNode.attrs.id
+                    ? Number.parseInt(deviceNode.attrs.id, 10)
+                    : Number.NaN;
+                return Number.isSafeInteger(parsedId) && parsedId >= 0
+                    ? this.toDeviceJid(userJid, parsedId)
+                    : null;
+            })
+                .filter((jid) => jid !== null))
+        ];
+    }
+    normalizeUsers(userJids) {
+        return [...new Set(userJids.map((jid) => this.normalizeUserJid(jid)))];
+    }
+    normalizeUserJid(jid) {
+        const { user } = parseSignalAddressFromJid(jid);
+        const { server } = splitJid(jid);
+        return `${user}@${server}`;
+    }
+    toDeviceJid(userJid, deviceId) {
+        const parsed = splitJid(userJid);
+        if (deviceId === 0) {
+            return `${parsed.user}@${parsed.server}`;
+        }
+        return `${parsed.user}:${deviceId}@${parsed.server}`;
+    }
+    makeSid() {
+        return `${Date.now()}.${randomInt(1000000)}`;
+    }
+}