@stone-wpp/ofc 1.0.6 → 1.0.7

package/README.md

@@ -18,7 +18,7 @@
 
 <br>
 
-<a href="https://github.com/dylan-Modz/stone-wpp-ofc"><img src="https://img.shields.io/badge/VERS%C3%83O-1.0.6-00BFFF?style=for-the-badge&logo=github&logoColor=white&labelColor=111820" alt="Versão 1.0.6 do código no GitHub"></a>
+<a href="https://github.com/dylan-Modz/stone-wpp-ofc"><img src="https://img.shields.io/badge/VERS%C3%83O-1.0.7-00BFFF?style=for-the-badge&logo=github&logoColor=white&labelColor=111820" alt="Versão 1.0.7 do código no GitHub"></a>
 <img src="https://img.shields.io/badge/NODE.JS-20%2B-111820?style=for-the-badge&logo=node.js&logoColor=00BFFF" alt="Node.js 20 ou superior">
 <img src="https://img.shields.io/badge/LICENSE-MIT-00BFFF?style=for-the-badge&labelColor=111820" alt="Licença MIT">
 
@@ -38,127 +38,73 @@
 
 ---
 
-## 📚 DOCUMENTAÇÃO COMPLETA
+## 🚀 Stone WPP 1.0.7 — novidades e melhorias
 
-A documentação principal da **Stone WPP** está disponível no nosso site oficial, com navegação por categorias, pesquisa e exemplos. Em vez de repetir todos os tutoriais aqui no npm, centralizamos as explicações no site para você encontrar cada recurso no lugar certo.
+A **1.0.7** apresenta um módulo totalmente novo de chamadas e aperfeiçoa recursos que a Stone WPP já oferecia.
 
-<div align="center">
-
-### **[🌐 ABRIR DOCUMENTAÇÃO — STONE WPP](https://stone-wpp.squareweb.app/)**
-
-**https://stone-wpp.squareweb.app/**
-
-</div>
-
-| O que você encontra | Conteúdo |
-| :--- | :--- |
-| 🚀 **Primeiros passos** | Instalação, configuração e uso inicial. |
-| 🔐 **Autenticação** | Sessão, conexão e reconexão. |
-| 💬 **Mensagens** | Envio, recebimento e eventos. |
-| 🧩 **Botões** | Exemplos e referências das mensagens interativas. |
-| 👥 **Grupos e comunidades** | Operações e gerenciamento. |
-| 📢 **Canais** | Métodos e recursos disponíveis. |
-| ⚙️ **Outros módulos** | API, DataLayer (armazenamento), Extensions (extensões) e funcionalidades relacionadas. |
-
-> **Importante:** a Stone WPP está em desenvolvimento. Consulte a documentação para conhecer os recursos disponíveis e suas limitações. Nem todas as funções planejadas estão implementadas.
+### 🆕 Novidades desta versão
 
----
-
-## 🛡️ Proteção nativa dos grupos — v1.0.6
+**📞 VoIP — novo módulo experimental**
 
-A `groupProtection` integra proteção contra flood, mensagens de pagamento em rajada, citações suspeitas e indícios de mensagens invisíveis. Ela reutiliza o recebimento, o retry e o PDO nativos da Stone. É **opcional** e **não depende de patches externos**.
+A Stone agora oferece a interface `stone.calls` para trabalhar com chamadas usando **a mesma conexão autenticada do WhatsApp**.
 
-A função pertence à categoria **Grupos → Configurações de grupos**, no site de documentação.
-
-```js
-// 1. Detectar e avisar (padrão: não pune automaticamente)
-await stone.groupProtection(grupoJid, { enabled: true })
+- **Chamadas de voz:** iniciar, atender, recusar e encerrar ligações.
+- **Música e áudio:** carregar arquivos de áudio e transmitir áudio em tempo real, conforme o suporte do ambiente.
+- **Eventos de chamadas:** acompanhar ligações recebidas, alterações de estado e encerramentos.
+- **Links e convites:** gerar links de chamada de voz ou vídeo e compartilhá-los com grupos.
+- **Chamadas em grupo:** novas interfaces para iniciar, entrar e sair de chamadas, ainda em caráter experimental.
+- **Controle do módulo:** consultar a disponibilidade dos recursos com `getVoipStatus()` e `getCapabilities()`.
 
-// 2. Ouvir ocorrências e resultados
-stone.ev.on('group-protection.alert', alerta => {
-  console.log(alerta.reason, alerta.severity, alerta.participant)
-})
-stone.ev.on('group-protection.action', resultado => {
-  console.log(resultado)
-})
+> **VoIP é uma funcionalidade nova e experimental.** Alguns recursos, especialmente as chamadas em grupo, dependem da compatibilidade com o WhatsApp e podem não estar disponíveis em todos os ambientes.
 
-// 3. Moderação automática opcional (use apenas em grupos administrados por você)
-await stone.groupProtection(grupoJid, {
-  enabled: true,
-  mode: 'protect',
-  paymentBurst: 3,
-  messageBurst: 14,
-  windowMs: 8000,
-  lockMs: 12000,
-  editNotice: true // edita apenas o aviso criado pelo próprio bot
-})
+**🔎 Novas ferramentas de diagnóstico**
 
-// 4. Consultar ou desativar
-console.log(await stone.groupProtection(grupoJid))
-await stone.groupProtection(grupoJid, { enabled: false })
-```
+- `resolveJidMapping(jid)` — consulta o mapeamento conhecido entre identificadores PN e LID.
+- `inspectSignalSession(jid)` — consulta a existência de uma sessão criptográfica Signal.
 
-Os modos são `alert` (apenas alertas), `delete` (tenta apagar), `remove` (tenta apagar e remover participante) e `protect` (também fecha temporariamente o grupo). Ações administrativas exigem que o bot seja administrador e **não são disparadas por simples falha de descriptografia**.
+### 🛠️ Melhorias nas funções que já existiam
 
-Agora a proteção também oferece **lista de imunidade** (`immunity`), **telemetria de recibos de retry e PDO**, **histórico de incidentes** e **persistência opcional** com Stone Store. O `PDO` e a descriptografia continuam sendo os mecanismos originais da Stone, sem alteração das chaves.
+- **Downloads de mídia:** recuperação aprimorada quando a URL direta responde com HTTP 403, 404 ou 410, tentando a URL original quando possível.
+- **Arquivos e descriptografia:** identificação mais clara de mídias sem chave e limites de espera para evitar processamento preso em tentativas de recuperação.
+- **Identificadores PN/LID:** tratamento aprimorado dos JIDs de usuários e dispositivos nas respostas da sincronização USync.
+- **Estabilidade e integração:** ajustes no tratamento dos eventos e na consistência das informações de sessão, mantendo os recursos de mensagens, grupos e canais.
 
-Para adicionar até três monitores complementares, use `monitors: [monitor1, monitor2, monitor3]` ou `monitorFactories` para criar/reconectar sessões extras após queda. O pareamento exige autorização: o código pode ser entregue ao titular usando `onPairingCode`, mas nunca é confirmado automaticamente em nome dele.
-
-```js
-import { createStoneStore } from '@stone-wpp/ofc'
-const store = await createStoneStore({ type: 'json', path: './dados/protecao.json' })
-await stone.groupProtection(grupoJid, {
-  enabled: true,
-  mode: 'alert',
-  immunity: [administradorJid],
-  observeReceipts: true,
-  receiptBurst: 6,
-  store
-})
-// Após reiniciar com a mesma base de dados:
-await stone.groupProtection(grupoJid, { restore: true, store })
-const { history } = await stone.groupProtection(grupoJid, { getHistory: true })
-console.log(history)
-```
-
-Os registros de histórico contêm somente metadados sanitizados, sem copiar texto ou ciphertext das mensagens. Recibos e PDO são apenas sinais técnicos: não autorizam expulsão automática.
+---
 
-### ✏️ Editar mensagens da própria conta
+## 📚 Documentação
 
-A Stone já suporta edição nativa com `sendMessage(jid, { text, edit: key })`. A v1.0.6 adiciona o atalho `editMessage`, documentado em **Mensagens → Apagar e editar**:
+O site oficial concentra os guias, exemplos e referências das funções disponíveis na Stone WPP.
 
-```js
-const enviada = await stone.sendMessage(grupoJid, { text: 'Aviso inicial' })
-await stone.editMessage(grupoJid, enviada.key, 'Aviso atualizado')
-```
+**[📖 Acessar a documentação completa](https://stone-wpp.squareweb.app/)**
 
-O WhatsApp não garante que seja possível editar texto escrito por terceiros; um administrador pode excluir uma mensagem alheia, mas não reescrevê-la em nome de outra pessoa.
-
-**Documentação completa:** [groupProtection e seus limites](docs/group-protection.md) · [Configurações de grupos no site](https://stone-wpp.squareweb.app/#/groups/configuracoes) · [Apagar e editar no site](https://stone-wpp.squareweb.app/#/messages/apagar).
+| Área | O que você encontra |
+| :--- | :--- |
+| Conexão e autenticação | Sessão, eventos e reconexão |
+| Mensagens e mídias | Envio, recebimento, downloads e arquivos |
+| Grupos e comunidades | Administração e operações de grupos |
+| Canais | Recursos de canais do WhatsApp |
+| Chamadas | Métodos e eventos do novo módulo VoIP |
+| Outros módulos | API, armazenamento e extensões |
 
 ---
 
-## 📦 INSTALAÇÃO PELO NPM
+## 📦 Instalação
+
+**Requisito:** Node.js 20 ou superior.
 
 ```bash
 npm install @stone-wpp/ofc
 ```
 
-**Requisitos:** Node.js **20+**. Biblioteca em JavaScript com suporte a ES Modules.
-
-Para instalar no **Termux**, dentro da pasta da sua aplicação:
+Para utilizar o código disponível diretamente no GitHub:
 
 ```bash
-pkg update -y
-pkg install nodejs-lts git -y
-npm install @stone-wpp/ofc
+npm install github:dylan-Modz/stone-wpp-ofc#main
 ```
 
-No Android, algumas dependências podem exigir suporte nativo. Prefira instalar na pasta privada do Termux.
-
 ---
 
-## ⚡ EXEMPLO RÁPIDO
+## ⚡ Exemplo rápido
 
 ```js
 import createStone, { useMultiFileAuthState } from '@stone-wpp/ofc'
@@ -173,9 +119,7 @@ stone.ev.on('connection.update', ({ connection }) => {
 })
 ```
 
-Para entender cada método, opções de conexão, eventos e exemplos, acesse a **[documentação oficial](https://stone-wpp.squareweb.app/)**.
-
-> A Stone WPP é uma **biblioteca**, não um bot pronto. Não possui `npm start` próprio. Proteja suas sessões e credenciais; não as publique em repositórios.
+Para explorar os métodos e exemplos de integração, consulte a **[documentação oficial](https://stone-wpp.squareweb.app/)**.
 
 ---
 

package/lib/Signal/lid-mapping.js

@@ -182,7 +182,15 @@ export class LIDMappingStore {
                     const lidUser = jidDecode(pair.lid)?.user;
                     if (!lidUser)
                         continue;
-                    for (const device of usyncFetch[pair.pn]) {
+                    // USync may reply with a device-specific PN instead of the normalized request.
+                    // Resolve both forms to avoid iterating over an undefined device list.
+                    const normalizedPairPn = jidNormalizedUser(pair.pn);
+                    const devices = usyncFetch[normalizedPairPn] ?? usyncFetch[pair.pn];
+                    if (!devices?.length) {
+                        this.logger.warn({ pn: pair.pn }, 'USync returned an unmatched PN mapping');
+                        continue;
+                    }
+                    for (const device of devices) {
                         const deviceSpecificLid = `${lidUser}${!!device ? `:${device}` : ``}@${device === 99 ? 'hosted.lid' : 'lid'}`;
                         this.logger.trace(`getLIDForPN: USYNC success for ${pair.pn} → ${deviceSpecificLid} (user mapping with device ${device})`);
                         const deviceSpecificPn = `${pnUser}${!!device ? `:${device}` : ``}@${device === 99 ? 'hosted' : 's.whatsapp.net'}`;

package/lib/Socket/index.d.ts

@@ -256,5 +256,5 @@ declare const makeWASocket: (config: UserFacingSocketConfig) => {
     }[] | undefined>;
     fetchAccountReachoutTimelock: () => Promise<import("../index.js").ReachoutTimelockState>;
     fetchNewChatMessageCap: () => Promise<import("../index.js").NewChatMessageCapInfo>;
-} & import('./stone-features.js').StoneAdditionalMethods & import('./group-protection.js').GroupProtectionMethods;
+} & import('./stone-features.js').StoneAdditionalMethods & import('./group-protection.js').GroupProtectionMethods & { calls: import('./stone-calls.js').StoneCalls };
 export default makeWASocket;

package/lib/Socket/index.js

@@ -2,6 +2,7 @@ import { DEFAULT_CONNECTION_CONFIG } from '../Defaults/index.js';
 import { makeCommunitiesSocket } from './communities.js';
 import { createStoneAdditionalMethods } from './stone-features.js';
 import { createGroupProtectionMethods } from './group-protection.js';
+import { createStoneCalls } from './stone-calls.js';
 // export the last socket layer
 const makeWASocket = (config) => {
     const newConfig = {
@@ -9,6 +10,6 @@ const makeWASocket = (config) => {
         ...config
     };
     const socket = makeCommunitiesSocket(newConfig);
-    return Object.assign(socket, createStoneAdditionalMethods(socket), createGroupProtectionMethods(socket));
+    return Object.assign(socket, createStoneAdditionalMethods(socket), createGroupProtectionMethods(socket), { calls: createStoneCalls(socket) });
 };
 export default makeWASocket;

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);
@@ -1492,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') {
@@ -1664,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)
+  }
+}