@stone-wpp/ofc 1.0.5 → 1.0.7

package/lib/Socket/messages-recv.js

@@ -13,6 +13,7 @@ import { buildMergedTcTokenIndexWrite, isTcTokenExpired, readTcTokenIndex, resol
 import { areJidsSameUser, binaryNodeToString, getAllBinaryNodeChildren, getBinaryNodeChild, getBinaryNodeChildBuffer, getBinaryNodeChildren, getBinaryNodeChildString, getBinaryNodeChildUInt, isJidGroup, isJidNewsletter, isJidStatusBroadcast, isLidUser, isPnUser, jidDecode, jidNormalizedUser, S_WHATSAPP_NET } from '../WABinary/index.js';
 import { extractGroupMetadata } from './groups.js';
 import { makeMessagesSocket } from './messages-send.js';
+import { parseStoneCallStanza } from './stone-call-signaling.js';
 const ENFORCEMENT_TYPE_VALUES = new Set(Object.values(ReachoutTimelockEnforcementType));
 function isValidEnforcementType(value) {
     return typeof value === 'string' && ENFORCEMENT_TYPE_VALUES.has(value);
@@ -37,6 +38,10 @@ export const makeMessagesRecvSocket = (config) => {
     // Debounce identity-change session refreshes per JID to avoid bursts
     const identityAssertDebounce = new NodeCache({ stdTTL: 5, useClones: false });
     let sendActiveReceipts = false;
+    const observePdo = data => {
+        try { ev.emit('group-protection.pdo', data); }
+        catch (error) { logger.debug({ error }, 'PDO telemetry listener failed'); }
+    };
     const fetchMessageHistory = async (count, oldestMsgKey, oldestMsgTimestamp) => {
         if (!authState.creds.me?.id) {
             throw new Boom('Not authenticated');
@@ -69,6 +74,9 @@ export const makeMessagesRecvSocket = (config) => {
         await delay(2000);
         if (!(await placeholderResendCache.get(messageKey?.id))) {
             logger.debug({ messageKey }, 'message received while resend requested');
+            if (isJidGroup(messageKey?.remoteJid)) {
+                observePdo({ remoteJid: messageKey.remoteJid, messageId: messageKey.id, status: 'resolved' });
+            }
             return 'RESOLVED';
         }
         const pdoMessage = {
@@ -83,8 +91,14 @@ export const makeMessagesRecvSocket = (config) => {
             if (await placeholderResendCache.get(messageKey?.id)) {
                 logger.debug({ messageKey }, 'PDO message without response after 8 seconds. Phone possibly offline');
                 await placeholderResendCache.del(messageKey?.id);
+                if (isJidGroup(messageKey?.remoteJid)) {
+                    observePdo({ remoteJid: messageKey.remoteJid, messageId: messageKey.id, status: 'timeout' });
+                }
             }
         }, 8000);
+        if (isJidGroup(messageKey?.remoteJid)) {
+            observePdo({ remoteJid: messageKey.remoteJid, messageId: messageKey.id, status: 'requested' });
+        }
         return sendPeerDataOperationMessage(pdoMessage);
     };
     const handleMexNotification = async (node) => {
@@ -1175,6 +1189,19 @@ export const makeMessagesRecvSocket = (config) => {
             const items = getBinaryNodeChildren(content[0], 'item');
             ids.push(...items.map(i => i.attrs.id));
         }
+        // Metadata somente: recibos de retry não comprovam ação maliciosa.
+        if (attrs.type === 'retry' && isJidGroup(remoteJid) && attrs.participant) {
+            for (const id of ids.filter(Boolean)) {
+                try {
+                    ev.emit('group-protection.receipt', {
+                        remoteJid, messageId: id, participant: attrs.participant,
+                        type: 'retry', receivedAt: Date.now()
+                    });
+                } catch (error) {
+                    logger.debug({ error }, 'receipt security telemetry failed');
+                }
+            }
+        }
         try {
             await Promise.all([
                 receiptMutex.mutex(async () => {
@@ -1300,7 +1327,7 @@ export const makeMessagesRecvSocket = (config) => {
                     && !msg.key.fromMe
                     && String(node?.attrs?.type || '').toLowerCase() !== 'reaction') {
                     try {
-                        ev.emit('tokito.security.ciphertext', {
+                        const securityObservation = {
                             remoteJid: msg.key.remoteJid,
                             messageId: msg.key.id,
                             participant: msg.key.participant || msg.participant || node?.attrs?.participant || '',
@@ -1309,7 +1336,10 @@ export const makeMessagesRecvSocket = (config) => {
                             encType: encNode?.attrs?.type || null,
                             messageTimestamp: msg.messageTimestamp,
                             receivedAt: Date.now()
-                        });
+                        };
+                        // Evento genérico da Stone, preservando o evento legado para compatibilidade.
+                        ev.emit('group-protection.ciphertext', securityObservation);
+                        ev.emit('tokito.security.ciphertext', securityObservation);
                     } catch (err) {
                         logger.debug({ err }, 'ciphertext observation failed');
                     }
@@ -1463,42 +1493,24 @@ export const makeMessagesRecvSocket = (config) => {
     };
     const handleCall = async (node) => {
         try {
-            const { attrs } = node;
             const [infoChild] = getAllBinaryNodeChildren(node);
             if (!infoChild) {
                 throw new Boom('Missing call info in call node');
             }
             const status = getCallStatusFromNode(infoChild);
-            const callId = infoChild.attrs['call-id'];
-            const from = infoChild.attrs.from || infoChild.attrs['call-creator'];
-            const call = {
-                chatId: attrs.from,
-                from,
-                callerPn: infoChild.attrs['caller_pn'],
-                id: callId,
-                date: new Date(+attrs.t * 1000),
-                offline: !!attrs.offline,
-                status
-            };
-            if (status === 'relaylatency') {
-                const latencyValue = infoChild.attrs.latency || infoChild.attrs['latency_ms'] || infoChild.attrs['latency-ms'];
-                const latencyMs = latencyValue ? Number(latencyValue) : undefined;
-                if (Number.isFinite(latencyMs)) {
-                    call.latencyMs = latencyMs;
-                }
-            }
+            // Apenas metadados de sinalização: não copie chaves, tokens ou payloads.
+            const call = parseStoneCallStanza(node, status);
+            if (!call) throw new Boom('Missing call id in call node');
             if (status === 'offer') {
-                call.isVideo = !!getBinaryNodeChild(infoChild, 'video');
-                call.isGroup = infoChild.attrs.type === 'group' || !!infoChild.attrs['group-jid'];
-                call.groupJid = infoChild.attrs['group-jid'];
                 await callOfferCache.set(call.id, call);
             }
             const existingCall = await callOfferCache.get(call.id);
-            // use existing call info to populate this event
             if (existingCall) {
-                call.isVideo = existingCall.isVideo;
-                call.isGroup = existingCall.isGroup;
-                call.callerPn = call.callerPn || existingCall.callerPn;
+                for (const field of ['isVideo', 'isGroup', 'groupJid', 'callerPn', 'callCreator', 'joinable']) {
+                    if (call[field] === undefined || call[field] === null) {
+                        call[field] = existingCall[field];
+                    }
+                }
             }
             // delete data once call has ended
             if (status === 'reject' || status === 'accept' || status === 'timeout' || status === 'terminate') {
@@ -1635,9 +1647,16 @@ export const makeMessagesRecvSocket = (config) => {
         await processNode('message', node, 'processing message', handleMessage);
     });
     ws.on('CB:call', async (node) => {
+        // O motor VoIP gerencia a sinalização + o ACK no mesmo websocket.
+        // Evite ACK duplicado quando seu handler estiver ativo.
+        if (ws._stoneVoipActive) return;
         await processNode('call', node, 'handling call', handleCall);
     });
     ws.on('CB:receipt', async (node) => {
+        const tag = Array.isArray(node?.content) ? node.content.find(child => child?.tag)?.tag : null;
+        if (ws._stoneVoipActive && ['offer','accept','preaccept','terminate','transport','relaylatency','mute_v2'].includes(tag)) {
+            return;
+        }
         await processNode('receipt', node, 'handling receipt', handleReceipt);
     });
     ws.on('CB:notification', async (node) => {

package/lib/Socket/messages-send.js

@@ -1044,14 +1044,19 @@ export const makeMessagesSocket = (config) => {
         messageRetryManager,
         updateMemberLabel,
         updateMediaMessage: async (message) => {
+            if (!message?.key?.id) {
+                throw new Boom('Media retry requires a valid message key', { statusCode: 400 });
+            }
             const content = assertMediaContent(message.message);
             const mediaKey = content.mediaKey;
+            if (!mediaKey?.length) {
+                throw new Boom('Media retry requires the original media key', { statusCode: 400 });
+            }
             const meId = authState.creds.me.id;
             const node = encryptMediaRetryRequest(message.key, mediaKey, meId);
             let error = undefined;
-            await Promise.all([
-                sendNode(node),
-                waitForMsgMediaUpdate(async (update) => {
+            // Register the listener before sending, and always cap the wait for a response.
+            const waitForUpdate = waitForMsgMediaUpdate(async (update) => {
                     const result = update.find(c => c.key.id === message.key.id);
                     if (result) {
                         if (result.error) {
@@ -1077,8 +1082,8 @@ export const makeMessagesSocket = (config) => {
                         }
                         return true;
                     }
-                })
-            ]);
+                }, config.defaultQueryTimeoutMs || 60000);
+            await Promise.all([waitForUpdate, sendNode(node)]);
             if (error) {
                 throw error;
             }

package/lib/Socket/socket.js

@@ -12,6 +12,7 @@ import { BinaryInfo } from '../WAM/BinaryInfo.js';
 import { USyncQuery, USyncUser } from '../WAUSync/index.js';
 import { WebSocketClient } from './Client/index.js';
 import { executeWMexQuery } from './mex.js';
+import { hasCompletedStonePairing } from './stone-pairing-state.js';
 /**
  * Connects to WA servers and performs:
  * - simple queries (no retry mechanism, wait for connection establishment)
@@ -317,7 +318,9 @@ export const makeSocket = (config) => {
         logger.trace({ handshake }, 'handshake recv from WA');
         const keyEnc = noise.processHandshake(handshake, creds.noiseKey);
         let node;
-        if (!creds.me) {
+        // requestPairingCode() sets creds.me before the phone confirms pairing.
+        // A JID alone is NOT proof of authentication; only a signed account is.
+        if (!hasCompletedStonePairing(creds)) {
             node = generateRegistrationNode(creds, config);
             logger.info({ node }, 'not logged in, attempting registration...');
         }
@@ -594,6 +597,9 @@ export const makeSocket = (config) => {
         void end(new Boom(msg || 'Intentional Logout', { statusCode: DisconnectReason.loggedOut }));
     };
     const requestPairingCode = async (phoneNumber, customPairingCode) => {
+        if (hasCompletedStonePairing(authState.creds)) {
+            throw new Error('Esta sessão Stone já está vinculada. Não solicite outro código de pareamento.');
+        }
         const pairingCode = customPairingCode ?? bytesToCrockford(randomBytes(5));
         if (customPairingCode && customPairingCode?.length !== 8) {
             throw new Error('Custom pairing code must be exactly 8 chars');

package/lib/Socket/stone-call-audio.js

@@ -0,0 +1,118 @@
+import { spawn } from 'node:child_process'
+import { access } from 'node:fs/promises'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+const SAMPLE_RATE = 16000
+const FRAME_MS = 20
+const SAMPLES = SAMPLE_RATE * FRAME_MS / 1000
+const STDERR_LIMIT = 8192
+
+/**
+ * Decodifica qualquer arquivo reconhecido pelo FFmpeg em quadros PCM de
+ * 20 ms, 16 kHz, mono, Float32Array. É uma fonte de áudio, não um socket VoIP.
+ * Um transporte de mídia conectado precisa consumir os quadros.
+ */
+export async function* decodeStoneCallAudio(inputPath, options = {}) {
+  if (typeof inputPath !== 'string' || !inputPath.trim()) {
+    throw new TypeError('Informe o arquivo de áudio')
+  }
+  await access(inputPath)
+  const { ffmpegPath = 'ffmpeg', signal } = options
+  if (typeof ffmpegPath !== 'string' || !ffmpegPath.trim()) {
+    throw new TypeError('Executável FFmpeg inválido')
+  }
+  if (signal?.aborted) throw signal.reason ?? new Error('Operação cancelada')
+  const child = spawn(ffmpegPath, [
+    '-nostdin', '-hide_banner', '-loglevel', 'error',
+    '-i', inputPath, '-vn', '-sn', '-dn',
+    '-ac', '1', '-ar', String(SAMPLE_RATE), '-f', 'f32le', 'pipe:1'
+  ], { stdio: ['ignore', 'pipe', 'pipe'] })
+
+  let spawnError = null
+  let stderr = ''
+  const closed = new Promise(resolve => {
+    child.once('error', error => { spawnError = error })
+    child.once('close', (code, closeSignal) => resolve({ code, closeSignal }))
+  })
+  const stop = () => { if (!child.killed) child.kill('SIGTERM') }
+  signal?.addEventListener('abort', stop, { once: true })
+  child.stderr?.on('data', data => {
+    stderr = (stderr + String(data)).slice(-STDERR_LIMIT)
+  })
+
+  let pending = Buffer.alloc(0)
+  const frameBytes = SAMPLES * Float32Array.BYTES_PER_ELEMENT
+  try {
+    for await (const chunk of child.stdout) {
+      if (signal?.aborted) throw signal.reason ?? new Error('Operação cancelada')
+      pending = pending.length ? Buffer.concat([pending, chunk]) : chunk
+      while (pending.length >= frameBytes) {
+        const frame = new Float32Array(SAMPLES)
+        for (let i = 0; i < SAMPLES; i++) frame[i] = pending.readFloatLE(i * 4)
+        pending = pending.subarray(frameBytes)
+        yield frame
+      }
+    }
+    const outcome = await closed
+    if (spawnError) throw spawnError
+    if (signal?.aborted) throw signal.reason ?? new Error('Operação cancelada')
+    if (outcome.code !== 0) {
+      throw new Error(`Falha FFmpeg (${outcome.code ?? outcome.closeSignal}): ${stderr.trim()}`)
+    }
+    if (pending.length) {
+      if (pending.length % 4 !== 0) throw new Error('Frame PCM inválido')
+      const frame = new Float32Array(SAMPLES)
+      for (let i = 0; i < pending.length / 4; i++) frame[i] = pending.readFloatLE(i * 4)
+      yield frame
+    }
+  } finally {
+    stop()
+    signal?.removeEventListener('abort', stop)
+    await closed
+  }
+}
+
+/**
+ * Alimenta um transporte de mídia real, quando disponível, regulando buffer.
+ * Não negocia chamada e não simula conexão. Recebe as funções do transporte
+ * como injeção de dependência para não duplicar sessões do WhatsApp.
+ */
+export async function feedStoneCallAudio(frames, {
+  feedAudio, getBufferedMs, maxBufferedMs = 600, resumeBelowMs = 200,
+  idleTimeoutMs = 30000, signal
+} = {}) {
+  if (typeof feedAudio !== 'function' || typeof getBufferedMs !== 'function') {
+    throw new TypeError('É necessário fornecer o transporte de áudio e a leitura de buffer')
+  }
+  if (!Number.isFinite(maxBufferedMs) || !Number.isFinite(resumeBelowMs) ||
+      resumeBelowMs < 0 || maxBufferedMs < resumeBelowMs || maxBufferedMs > 10000) {
+    throw new RangeError('Limites do buffer de áudio inválidos')
+  }
+  if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs <= 0) {
+    throw new RangeError('Tempo limite inválido')
+  }
+  let count = 0
+  for await (const frame of frames) {
+    if (signal?.aborted) throw signal.reason ?? new Error('Operação cancelada')
+    if (!(frame instanceof Float32Array) || frame.length !== SAMPLES) {
+      throw new TypeError('Frame PCM inválido: esperado Float32Array de 320 amostras')
+    }
+    let started = 0
+    while (getBufferedMs() > maxBufferedMs) {
+      if (!started) started = Date.now()
+      if (Date.now() - started >= idleTimeoutMs) {
+        throw new Error('Transporte de mídia não esvazia o buffer de áudio')
+      }
+      await sleep(20, undefined, { signal })
+      if (getBufferedMs() <= resumeBelowMs) break
+    }
+    await feedAudio(frame)
+    count++
+  }
+  return { frames: count, durationMs: count * FRAME_MS }
+}
+
+export const STONE_CALL_AUDIO_FORMAT = Object.freeze({
+  sampleRate: SAMPLE_RATE, channels: 1,
+  samplesPerFrame: SAMPLES, frameMs: FRAME_MS, format: 'f32le'
+})

package/lib/Socket/stone-call-keys.js

@@ -0,0 +1,96 @@
+import { proto } from '../../Protocol/index.js'
+import { encodeWAMessage, unpadRandomMax16 } from '../Utils/generics.js'
+
+const children = node => Array.isArray(node?.content) ? node.content.filter(Boolean) : []
+
+// Seleciona envelopes sem expor qualquer chave no evento de chamada.
+export function collectCallKeyEnvelopes(node) {
+  const offer = node?.tag === 'call' ? children(node).find(x => x.tag === 'offer') : node
+  if (!offer) return []
+  const direct = children(offer).filter(x => x.tag === 'enc')
+  const destinations = children(offer).filter(x => x.tag === 'destination')
+  const nested = destinations.flatMap(group =>
+    children(group).filter(x => x.tag === 'to')
+      .flatMap(target => children(target).filter(x => x.tag === 'enc')))
+  return [...direct, ...nested].filter(x =>
+    (x.attrs?.type === 'msg' || x.attrs?.type === 'pkmsg') &&
+    x.content instanceof Uint8Array && x.content.length > 0)
+}
+
+// Descriptografa chave de chamada para uso INTERNO, usando Signal da sessão Stone.
+// Não persiste material sensível nem envia a chave a eventos ou logs.
+export async function decryptIncomingCallKey(signalRepository, offerNode, peerDeviceJid) {
+  if (typeof signalRepository?.decryptMessage !== 'function') {
+    throw new TypeError('Repositório de criptografia da Stone indisponível')
+  }
+  if (typeof peerDeviceJid !== 'string' || !/^[^@\s]+@[^@\s]+$/.test(peerDeviceJid)) {
+    throw new TypeError('Identificador do dispositivo de origem inválido')
+  }
+  for (const envelope of collectCallKeyEnvelopes(offerNode)) {
+    try {
+      const plain = Buffer.from(await signalRepository.decryptMessage({
+        jid: peerDeviceJid, type: envelope.attrs.type,
+        ciphertext: Buffer.from(envelope.content)
+      }))
+      try {
+        const message = proto.Message.decode(unpadRandomMax16(plain))
+        if (message.call?.callKey?.length === 32) {
+          return Buffer.from(message.call.callKey)
+        }
+      } finally {
+        plain.fill(0)
+      }
+    } catch {
+      // Envelopes destinados a outros dispositivos não interrompem a leitura.
+    }
+  }
+  return null
+}
+
+// Prepara envelopes criptografados (não envia oferta nem inicia chamada).
+export async function encryptCallKeyForDevices(signalRepository, ensureSessions, deviceJids, callKey) {
+  if (typeof signalRepository?.encryptMessage !== 'function') {
+    throw new TypeError('Repositório de criptografia da Stone indisponível')
+  }
+  if (typeof ensureSessions !== 'function') {
+    throw new TypeError('É necessário verificar as sessões dos dispositivos')
+  }
+  if (!Array.isArray(deviceJids) || deviceJids.length < 1 || deviceJids.length > 32 ||
+      deviceJids.some(jid => typeof jid !== 'string' || !/^[^@\s]+@[^@\s]+$/.test(jid)) ||
+      new Set(deviceJids).size !== deviceJids.length) {
+    throw new TypeError('Lista de dispositivos inválida ou duplicada')
+  }
+  if (!(callKey instanceof Uint8Array) || callKey.length !== 32) {
+    throw new TypeError('A chave de chamada precisa ter 32 bytes')
+  }
+  await ensureSessions(deviceJids)
+  const encoded = encodeWAMessage({ call: { callKey: Buffer.from(callKey) } })
+  try {
+    // Aguarde todas as criptografias antes de zerar o buffer compartilhado:
+    // Promise.all pode rejeitar enquanto outras operações ainda o utilizam.
+    const settled = await Promise.allSettled(deviceJids.map(async jid => {
+      const value = await signalRepository.encryptMessage({ jid, data: encoded })
+      if ((value.type !== 'msg' && value.type !== 'pkmsg') ||
+          !(value.ciphertext instanceof Uint8Array) || !value.ciphertext.length) {
+        throw new Error('Mensagem criptografada de chamada inválida')
+      }
+      return {
+        jid,
+        node: {
+          tag: 'enc', attrs: { v: '2', type: value.type, count: '0' },
+          content: Buffer.from(value.ciphertext)
+        },
+        identity: value.type === 'pkmsg'
+      }
+    }))
+    const failure = settled.find(entry => entry.status === 'rejected')
+    if (failure) throw failure.reason
+    const results = settled.map(entry => entry.value)
+    return {
+      destinations: results.map(x => ({ tag:'to', attrs:{jid:x.jid}, content:[x.node] })),
+      requiresDeviceIdentity: results.some(x => x.identity)
+    }
+  } finally {
+    if (typeof encoded.fill === 'function') encoded.fill(0)
+  }
+}

package/lib/Socket/stone-call-signaling.js

@@ -0,0 +1,127 @@
+import { randomBytes } from 'node:crypto'
+
+/**
+ * Normaliza metadados públicos de uma sinalização recebida sem reter nem
+ * expor os nós que carregam chaves E2EE, tokens ou credenciais de relay.
+ * Não é um decodificador de mídia nem um implementador de chamadas VoIP.
+ */
+export function parseStoneCallStanza(node, status) {
+  const attrs = node?.attrs ?? {}
+  const inner = Array.isArray(node?.content) ? node.content.find(child => child?.tag && child?.attrs) : null
+  const fields = inner?.attrs
+  if (!fields || typeof fields['call-id'] !== 'string' || !fields['call-id']) return null
+
+  const children = Array.isArray(inner.content) ? inner.content : []
+  const groupJid = fields['group-jid'] || fields.group_jid || null
+  const callCreator = fields['call-creator'] || fields.from || null
+  const timestamp = Number(attrs.t)
+  const date = Number.isFinite(timestamp) && timestamp > 0 ? new Date(timestamp * 1000) : new Date()
+  const value = {
+    id: fields['call-id'],
+    chatId: attrs.from ?? null,
+    from: fields.from || callCreator,
+    callCreator,
+    sourceJid: attrs.from ?? null,
+    stanzaId: attrs.id ?? null,
+    callerPn: fields.caller_pn ?? fields['caller_pn'] ?? null,
+    date,
+    offline: attrs.offline === '1' || attrs.offline === 'true' || attrs.offline === true,
+    status: typeof status === 'string' && status ? status : inner.tag
+  }
+  if (value.status === 'offer') {
+    value.isGroup = fields.type === 'group' || Boolean(groupJid) || String(attrs.from || '').endsWith('@call')
+    value.groupJid = groupJid
+    value.isVideo = children.some(child => child?.tag === 'video')
+    value.joinable = fields.joinable === '1' || fields.joinable === 'true'
+    value.reRing = fields['re-ring'] === '1'
+  }
+  if (value.status === 'relaylatency') {
+    const latency = fields.latency ?? fields.latency_ms ?? fields['latency-ms']
+    if (latency !== undefined && latency !== '') {
+      const ms = Number(latency)
+      if (Number.isFinite(ms) && ms >= 0) value.latencyMs = ms
+    }
+  }
+  return value
+}
+
+
+/**
+ * Primitivas de sinalização da Stone WPP.
+ * Apenas montam nós binários e não iniciam nenhuma ligação nem transportam mídia.
+ */
+export function createStoneCallStanza({ to, tag, callId, callCreator, attrs = {}, content }, random = randomBytes) {
+  if (typeof to !== 'string' || !/^[^@\s]+@[^@\s]+$/.test(to)) {
+    throw new TypeError('Destino da sinalização inválido')
+  }
+  if (!['offer', 'preaccept', 'accept', 'terminate', 'reject'].includes(tag)) {
+    throw new TypeError('Tipo da sinalização inválido')
+  }
+  if (typeof callId !== 'string' || !/^[A-Za-z0-9_-]{1,256}$/.test(callId)) {
+    throw new TypeError('Identificador da chamada inválido')
+  }
+  if (typeof callCreator !== 'string' || !/^[^@\s]+@[^@\s]+$/.test(callCreator)) {
+    throw new TypeError('Criador da chamada inválido')
+  }
+  if (!attrs || typeof attrs !== 'object' || Array.isArray(attrs) ||
+      Object.keys(attrs).some(key => key === 'call-id' || key === 'call-creator' ||
+        typeof attrs[key] !== 'string')) {
+    throw new TypeError('Atributos da sinalização inválidos')
+  }
+  if (content !== undefined && (!Array.isArray(content) || content.some(x => !x || typeof x.tag !== 'string'))) {
+    throw new TypeError('Conteúdo da sinalização inválido')
+  }
+  const bytes = Buffer.from(random(16))
+  if (bytes.length !== 16) throw new Error('Gerador de identificadores inválido')
+  const child = { tag, attrs: { 'call-id': callId, 'call-creator': callCreator, ...attrs } }
+  if (content !== undefined) child.content = content
+  return {
+    tag: 'call',
+    attrs: { to, id: bytes.toString('hex').toUpperCase() },
+    content: [child]
+  }
+}
+
+/**
+ * Formato de mídia anunciado no protocolo (não cria codec nem transmite áudio).
+ * A camada de mídia ainda precisa negociar transporte e chaves antes de uso real.
+ */
+export function createStoneCallMediaDescription(isVideo = false) {
+  const nodes = [
+    { tag: 'audio', attrs: { enc: 'opus', rate: '8000' } },
+    { tag: 'audio', attrs: { enc: 'opus', rate: '16000' } }
+  ]
+  if (isVideo) {
+    nodes.push({
+      tag: 'video',
+      attrs: {
+        enc: 'h.264', dec: 'H264',
+        screen_width: '1920', screen_height: '1080',
+        device_orientation: '0'
+      }
+    })
+  }
+  nodes.push({ tag: 'net', attrs: { medium: '3' } })
+  return nodes
+}
+
+/** Extrai o ID de um destino de grupo @call, sem expor o payload da oferta. */
+export function parseStoneCallServerJid(jid) {
+  if (typeof jid !== 'string' || !jid.endsWith('@call')) return null
+  const id = jid.slice(0, -'@call'.length)
+  return /^[A-Za-z0-9_-]{1,256}$/.test(id) ? id : null
+}
+
+/** Grupo: a recusa pertence à chamada e vai para <call-id>@call. */
+export function buildGroupCallRejectStanza(callId, callCreator, random = randomBytes) {
+  if (typeof callId !== 'string' || !/^[A-Za-z0-9_-]{1,256}$/.test(callId)) {
+    throw new TypeError('Identificador da chamada inválido')
+  }
+  if (typeof callCreator !== 'string' || !/^[^@\s]+@[^@\s]+$/.test(callCreator)) {
+    throw new TypeError('Criador da chamada inválido')
+  }
+  return createStoneCallStanza({
+    to: `${callId}@call`, tag: 'reject', callId, callCreator,
+    attrs: { count: '0' }
+  }, random)
+}

package/lib/Socket/stone-calls.d.ts

@@ -0,0 +1,76 @@
+export type StoneCallEvent = 'incoming' | 'state' | 'ended'
+export interface StoneCallInfo {
+  callId: string
+  id: string
+  status: string
+  chatId: string | null
+  peerJid: string | null
+  from: string | null
+  groupJid: string | null
+  callerPn: string | null
+  callCreator: string | null
+  sourceJid: string | null
+  stanzaId: string | null
+  joinable: boolean
+  reRing: boolean
+  latencyMs: number | null
+  isGroupCall: boolean
+  isVideo: boolean
+  date: Date
+  stateData: { state: string; endReason?: string }
+}
+export interface StoneCallCapabilities {
+  sharedSocket: true
+  incomingEvents: true
+  rejectIncomingCall: true
+  groupCallReject: boolean
+  incomingMetadata: true
+  callLinks: true
+  groupCallInvites: boolean
+  startCall: boolean
+  acceptCall: boolean
+  joinCall: boolean
+  liveAudio: boolean
+  audioFiles: boolean
+  videoMedia: boolean
+}
+export interface StoneCalls {
+  on(event: StoneCallEvent, handler: (call: StoneCallInfo) => void): StoneCalls
+  once(event: StoneCallEvent, handler: (call: StoneCallInfo) => void): StoneCalls
+  off(event: StoneCallEvent, handler: (call: StoneCallInfo) => void): StoneCalls
+  enableVoip(options?: { maxConcurrentCalls?: number; useRawUdpTransport?: boolean; logLevel?: string }): Promise<StoneCallCapabilities>
+  getVoipStatus(): { initialized: boolean; initializing: boolean; error: { code: string; message: string } | null }
+  getCapabilities(): StoneCallCapabilities
+  getCall(callId: string): StoneCallInfo | null
+  getCalls(): StoneCallInfo[]
+  rejectCall(callId: string): Promise<void>
+  createCallLink(type?: 'audio' | 'video', event?: { startTime: number }, timeoutMs?: number): Promise<string | undefined>
+  sendGroupCallInvite(groupJid: string, options?: { type?: 'audio' | 'video'; text?: string }): Promise<{
+    groupJid: string
+    type: 'audio' | 'video'
+    url: string
+    message: import('../Types/index.js').WAMessage
+  }>
+  /** Disponíveis SOMENTE depois de enableVoip() concluir com o motor de mídia carregado. */
+  startCall(options: { peerJid?: string; groupJid?: string; participants?: Array<{ jid: string; devices?: string[] }>; isVideo?: boolean; audioFile?: string }): Promise<string>
+  startGroupCall(options: { groupJid: string; participants: Array<{ jid: string; devices?: string[] }>; isVideo?: boolean; audioFile?: string }): Promise<string>
+  acceptCall(callId: string): Promise<void>
+  joinCall(callId: string): Promise<void>
+  leaveCall(callId: string): Promise<void>
+  endCall(callId: string): Promise<void>
+  loadAudio(callId: string, file: string): Promise<void>
+  playAudio(...args: any[]): never
+  setExternalAudioMode(callId: string, enabled: boolean): void
+  feedLiveAudio(callId: string, samples: Float32Array): number
+  getLiveBufferMs(callId: string): number
+  getFeedWatermarksMs(callId: string): unknown
+  setMute(callId: string, muted: boolean): void
+  destroy(): void
+}
+export declare function createStoneCalls(socket: {
+  ev: { on(event: string, handler: (event: any) => void): any; off(event: string, handler: (event: any) => void): any }
+  rejectCall(callId: string, from: string): Promise<void>
+  sendNode?: (node: any) => Promise<void>
+  createCallLink(type: 'audio' | 'video', event?: { startTime: number }, timeoutMs?: number): Promise<string | undefined>
+  sendGroupCallInvite?: (jid: string, options?: { type?: 'audio' | 'video'; text?: string }) => Promise<any>
+}): StoneCalls