@stone-wpp/ofc 1.0.5 → 1.0.6

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.5-00BFFF?style=for-the-badge&logo=github&logoColor=white&labelColor=111820" alt="Versão 1.0.5 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.6-00BFFF?style=for-the-badge&logo=github&logoColor=white&labelColor=111820" alt="Versão 1.0.6 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">
 
@@ -64,6 +64,80 @@ A documentação principal da **Stone WPP** está disponível no nosso site ofic
 
 ---
 
+## 🛡️ Proteção nativa dos grupos — v1.0.6
+
+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 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 })
+
+// 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)
+})
+
+// 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
+})
+
+// 4. Consultar ou desativar
+console.log(await stone.groupProtection(grupoJid))
+await stone.groupProtection(grupoJid, { enabled: false })
+```
+
+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**.
+
+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.
+
+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
+
+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**:
+
+```js
+const enviada = await stone.sendMessage(grupoJid, { text: 'Aviso inicial' })
+await stone.editMessage(grupoJid, enviada.key, 'Aviso atualizado')
+```
+
+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).
+
+---
+
 ## 📦 INSTALAÇÃO PELO NPM
 
 ```bash

package/docs/group-protection.md

@@ -0,0 +1,203 @@
+# groupProtection — proteção de grupos na Stone WPP
+
+A API nativa `sock.groupProtection(jid, options)` usa a recepção da própria Stone e
+não modifica o protocolo de criptografia. Detecta rajadas de mensagens de pagamento
+e flood, observa falhas de descriptografia, recibos de retry e solicitações PDO de
+recuperação. **Nenhuma dessas observações é garantia de ataque ou de mensagem recuperada.**
+
+## 1. Ativar sem risco
+
+```js
+await sock.groupProtection(grupoJid, {
+  enabled: true,
+  mode: 'alert',
+  observeInvisible: true,
+  observeReceipts: true
+})
+
+sock.ev.on('group-protection.alert', alerta => {
+  console.log(alerta.jid, alerta.reason, alerta.severity, alerta.verified)
+})
+```
+
+O modo `alert` não apaga conteúdo e não remove pessoas. Use-o em um grupo próprio
+para calibrar os limites antes de optar por moderação automática.
+
+## 2. Moderação automática e imunidade
+
+```js
+await sock.groupProtection(grupoJid, {
+  enabled: true,
+  mode: 'protect',
+  paymentBurst: 3,
+  messageBurst: 14,
+  windowMs: 8000,
+  lockMs: 12000,
+  editNotice: true,
+  immunity: [donoJid, moderadorJid]
+})
+```
+
+| Opção | Significado |
+| --- | --- |
+| `mode: 'alert'` | Só registra alertas (padrão) |
+| `mode: 'delete'` | Tenta excluir a mensagem de rajada verificada |
+| `mode: 'remove'` | Tenta excluir e remover participante |
+| `mode: 'protect'` | Tenta fechar temporariamente, excluir e remover |
+| `paymentBurst` | Número de mensagens de pagamento por remetente na janela (2–30) |
+| `messageBurst` | Número de mensagens por remetente na janela (3–100) |
+| `windowMs` | Janela de observação em milissegundos (1.000–60.000) |
+| `lockMs` | Intervalo de fechamento do grupo (3.000–120.000 ms) |
+| `immunity` | Até 200 JIDs que jamais serão removidos automaticamente |
+| `editNotice` | Edita **somente avisos enviados pelo bot**, nunca mensagens de terceiros |
+| `observeReceipts` | Observa recibos de retry (padrão: true) |
+| `receiptBurst` | Volume que gera alerta leve de recibos (3–50) |
+| `historyLimit` | Registros recentes mantidos por grupo (20–500) |
+
+O bot precisa ser administrador. Pessoas sem identidade confirmada, administradores
+e JIDs imunes não são expulsos. **PN e LID são tipos diferentes de identificador**:
+inclua as formas conhecidas na imunidade se aplicável. Rajadas de mensagens legítimas
+podem parecer ataques; ajuste os limites conforme o grupo.
+
+## 3. Recibos ocultos e PDO já existente
+
+A Stone já possui `requestPlaceholderResend`, retry e PDO. A proteção acrescenta
+**telemetria passiva** ao caminho nativo, sem duplicar solicitações:
+
+```js
+sock.ev.on('group-protection.pdo-observed', ({ jid, messageId, status }) => {
+  console.log('PDO do grupo:', jid, messageId, status)
+})
+
+sock.ev.on('group-protection.alert', alerta => {
+  if (alerta.reason === 'receipt-suspected') {
+    console.log('Rajada de retry observada — sem expulsão automática')
+  }
+})
+```
+
+`group-protection.receipt` é o evento bruto com `remoteJid`, `participant`,
+`messageId` e `type: 'retry'`. `group-protection.pdo` informa eventos nativos
+`requested`, `resolved` ou `timeout`; `group-protection.pdo-observed`
+exibe apenas os PDO dos grupos ativados. Recebimentos de retry e falhas de
+descriptografia são **sinais técnicos**, não prova de intenção maliciosa.
+Um pedido PDO pode falhar, expirar ou retornar sem recuperar o conteúdo.
+
+## 4. Salvar configurações e consultar histórico
+
+Use `createStoneStore` com JSON ou SQLite. O armazenamento é **opcional** e
+precisa ser informado explicitamente. Exemplo:
+
+```js
+import { createStoneStore } from '@stone-wpp/ofc'
+
+const store = await createStoneStore({ type: 'json', path: './dados/protecao.json' })
+await sock.groupProtection(grupoJid, {
+  enabled: true,
+  mode: 'alert',
+  store,
+  immunity: [donoJid],
+  historyLimit: 100
+})
+
+// Após reiniciar o bot, com o mesmo store:
+await sock.groupProtection(grupoJid, { restore: true, store })
+
+// Consultar últimos 30 registros, sem dados de mensagens:
+const status = await sock.groupProtection(grupoJid, { getHistory: true, limit: 30 })
+console.log(status.history)
+
+// Desativar e salvar o estado desligado:
+await sock.groupProtection(grupoJid, { enabled: false, store })
+```
+
+O histórico salva somente grupo, participante, tipo de alerta/ação, situação de
+moderação e horário. Não armazena automaticamente texto de mensagens, ciphertext
+ou chaves da sessão. A proteção só restaura grupos que o seu aplicativo indicar;
+o store **não inicia sessões nem descobre todos os grupos sozinho**.
+
+## 5. Até três monitores complementares com reconexão
+
+`monitors` aceita sockets Stone já criados. Para **recriação automática**
+de um monitor após queda temporária use `monitorFactories`: a função factory
+deve criar o socket autenticado e carregar/persistir sua própria sessão.
+
+```js
+await sock.groupProtection(grupoJid, {
+  enabled: true,
+  mode: 'alert',
+  monitorFactories: [
+    async ({ attempt }) => criarMonitorComSessaoSalva('auxiliar1', attempt),
+    async ({ attempt }) => criarMonitorComSessaoSalva('auxiliar2', attempt)
+  ],
+  monitorReconnectMs: 3000
+})
+
+sock.ev.on('group-protection.monitor', ({ index, status, error }) => {
+  console.log('Monitor:', index, status, error || '')
+})
+```
+
+### Pareamento autorizado de um monitor novo
+
+Se a sessão auxiliar ainda não foi vinculada, é possível solicitar um código
+**somente quando o titular configurar explicitamente** o número e callback.
+A Stone informa o código; o proprietário confirma no aplicativo WhatsApp.
+
+```js
+import makeStone, { useMultiFileAuthState } from '@stone-wpp/ofc'
+
+async function criarMonitor() {
+  const { state, saveCreds } = await useMultiFileAuthState('./sessao-monitor-1')
+  const monitor = makeStone({ auth: state })
+  monitor.ev.on('creds.update', saveCreds)
+  return monitor
+}
+await sock.groupProtection(grupoJid, {
+  enabled: true,
+  mode: 'alert',
+  monitorFactories: [{
+    create: criarMonitor,
+    phoneNumber: '5511999999999', // use seu número com DDI
+    onPairingCode({ code }) {
+      console.log('Vincule no WhatsApp do titular:', code)
+    }
+  }]
+})
+```
+
+Não há pareamento sem o usuário confirmar o código no telefone.
+Cada monitor precisa de pasta de credenciais distinta. Se houver logout,
+a reconexão para, evitando tentativas silenciosas.
+
+A função `criarMonitorComSessaoSalva` é criada **pela sua aplicação**;
+ela não é uma exportação da Stone. Ela deve utilizar suas próprias credenciais
+de WhatsApp, do mesmo modo que você cria a sessão principal. Cada número
+auxiliar precisa ser autenticado **com autorização do proprietário** e
+participar do grupo. Não há pareamento silencioso: em caso de logout (401),
+a proteção não tenta conectar novamente sem novo vínculo.
+
+`monitors` e `monitorFactories` juntos aceitam **até três** sessões adicionais.
+A Stone deduplica IDs recebidos de mais de uma sessão e observa apenas os
+grupos em que o monitor foi configurado. Uma mensagem omitida pelo WhatsApp
+para todas as sessões continua invisível.
+
+## 6. Status, erros e testes
+
+```js
+const state = await sock.groupProtection(grupoJid)
+console.log(state.enabled, state.mode, state.monitorCount)
+console.log(state.alerts, state.actions)
+```
+
+Eventos de acompanhamento:
+- `group-protection.alert` — motivo, gravidade, evidência limitada e origem.
+- `group-protection.action` — tentativa e resultado da moderação.
+- `group-protection.monitor` — monitor conectado, erro ou logout.
+- `group-protection.pdo-observed` — telemetria de recuperação de placeholder.
+
+Testes locais: `npm test`. Ative inicialmente `mode: 'alert'` em grupos controlados,
+verifique casos normais (pagamento legítimo, perda de conexão, um participante
+muito ativo) e só depois considere `delete`, `remove` ou `protect`.
+A proteção não falsifica mensagens atribuídas a terceiros, não garante
+detectar todos os bypasses e não substitui as regras oficiais do WhatsApp.

package/lib/Socket/group-protection.d.ts

@@ -0,0 +1,146 @@
+export type GroupProtectionMode = 'alert' | 'delete' | 'remove' | 'protect'
+
+/** Persistência opcional: utilize createStoneStore({ type: 'json' | 'sqlite', path }). */
+export interface GroupProtectionStore {
+  get<T = unknown>(key: string): Promise<T | undefined>
+  set(key: string, value: unknown): Promise<boolean>
+}
+
+export interface GroupProtectionHistoryEntry {
+  type: 'alert' | 'action'
+  jid: string
+  participant: string | null
+  reason: string | null
+  severity: string | null
+  action: string | null
+  mode: string | null
+  deleted: boolean
+  removed: boolean
+  locked: boolean
+  receivedAt: number
+}
+
+export interface GroupProtectionMonitor {
+  ev: {
+    on(name: string, fn: (...args: any[]) => void): unknown
+    off(name: string, fn: (...args: any[]) => void): unknown
+  }
+}
+
+/** Cria/recria sessão auxiliar do próprio usuário. O aplicativo ainda persiste a autenticação. */
+export interface GroupProtectionMonitorPairing {
+  create(args: { jid: string; attempt: number }): Promise<GroupProtectionMonitor>
+  /** Número com DDI para solicitar o código somente se a sessão não estiver registrada. */
+  phoneNumber?: string
+  /** Callback privado: mostre o código ao titular para confirmação no WhatsApp. */
+  onPairingCode?: (info: { jid: string; index: number; code: string }) => void | Promise<void>
+}
+
+export interface GroupProtectionOptions {
+  /** Desativada por padrão; chamar com {enabled: true} para ativar. */
+  enabled?: boolean
+  /** alert: apenas eventos. delete: apaga; remove: apaga + remove membro; protect: fecha temporariamente + apaga + remove. */
+  mode?: GroupProtectionMode
+  /** Mínimo de mensagens de pagamento do mesmo remetente por janela (padrão: 3). */
+  paymentBurst?: number
+  /** Mínimo de mensagens totais por janela (padrão: 14). */
+  messageBurst?: number
+  /** Janela de detecção em milissegundos (padrão: 8000). */
+  windowMs?: number
+  /** Tempo de fechamento temporário no modo protect (padrão: 12000). */
+  lockMs?: number
+  observeInvisible?: boolean
+  observePayments?: boolean
+  observeQuotes?: boolean
+  observeFlood?: boolean
+  /** Se true, publica um aviso do bot e edita o aviso ao concluir as ações. */
+  editNotice?: boolean
+  /** Até três sockets adicionais já autenticados e presentes nos grupos. */
+  monitors?: GroupProtectionMonitor[]
+  /** Factories de até 3 sessões extras já autenticadas; reconecta em queda temporária.
+   *  O próprio aplicativo deve criar os sockets e persistir as credenciais.
+   *  Logout não causa novo pareamento automático. */
+  monitorFactories?: Array<
+    ((args: { jid: string; attempt: number }) => Promise<GroupProtectionMonitor>)
+    | GroupProtectionMonitorPairing
+  >
+  monitorReconnectMs?: number
+  /** Recibos de retry são tratados apenas como telemetria, nunca prova de ataque. */
+  observeReceipts?: boolean
+  receiptBurst?: number
+  /** JIDs imunes a remoção (PN e LID são comparados separadamente). */
+  immunity?: string[]
+  /** Limite de registros mantidos por grupo, entre 20 e 500. */
+  historyLimit?: number
+  /** StoneStore opcional para persistir regras e histórico. */
+  store?: GroupProtectionStore
+  /** Restaura regras previamente salvas no store; requer store. */
+  restore?: boolean
+  /** Consulta o histórico sem modificar as configurações; requer store ou ativação prévia. */
+  getHistory?: boolean
+  /** Limita linhas retornadas na consulta de histórico. */
+  limit?: number
+}
+
+export interface GroupProtectionStatus {
+  jid: string
+  enabled: boolean
+  mode?: GroupProtectionMode
+  paymentBurst?: number
+  messageBurst?: number
+  windowMs?: number
+  lockMs?: number
+  observeInvisible?: boolean
+  observePayments?: boolean
+  observeQuotes?: boolean
+  observeFlood?: boolean
+  observeReceipts?: boolean
+  receiptBurst?: number
+  immunity?: string[]
+  historyLimit?: number
+  history?: GroupProtectionHistoryEntry[]
+  restored?: boolean
+  monitorCount: number
+  alerts: number
+  actions: number
+}
+
+export interface GroupProtectionAlert {
+  jid: string
+  participant: string
+  messageId: string
+  reason: 'payment' | 'flood' | 'invisible-suspected' | 'quoted-payment' | 'receipt-suspected'
+  severity: 'low' | 'medium' | 'high'
+  verified: boolean
+  source: string
+  evidence: Record<string, unknown>
+  mode: GroupProtectionMode
+  receivedAt: number
+}
+
+export interface GroupProtectionAction {
+  jid: string
+  participant?: string
+  messageId?: string
+  action?: 'reopen'
+  attemptedMode?: GroupProtectionMode
+  deleted?: boolean
+  removed?: boolean
+  locked?: boolean
+  ok?: boolean
+  error?: string
+  deleteError?: string
+  removeError?: string
+  lockError?: string
+  noticeEdited?: boolean
+  noticeError?: string
+  noticeEditError?: string
+}
+
+export interface GroupProtectionMethods {
+  /** Configura, consulta, restaura, desativa ou consulta histórico por grupo.
+   * Persistência exige store explícito; login de monitores exige autenticação prévia. */
+  groupProtection(jid: string, options?: GroupProtectionOptions): Promise<GroupProtectionStatus>
+}
+
+export declare function createGroupProtectionMethods(socket: unknown): GroupProtectionMethods

package/lib/Socket/group-protection.js

@@ -0,0 +1,571 @@
+/**
+ * Stone WPP - proteção de grupos baseada em sinais observados.
+ * Não modifica mensagens, não falsifica provas e não substitui o retry criptográfico.
+ */
+const PAYMENT_FIELDS = new Set([
+  'requestPaymentMessage', 'sendPaymentMessage', 'paymentInviteMessage',
+  'cancelPaymentRequestMessage', 'declinePaymentRequestMessage',
+  'orderMessage', 'invoiceMessage'
+])
+const PAYMENT_BUTTONS = new Set(['payment_info', 'review_and_pay', 'payment_instruction'])
+const DEFAULTS = Object.freeze({
+  enabled: true,
+  mode: 'alert', // alert | delete | remove | protect
+  paymentBurst: 3,
+  messageBurst: 14,
+  windowMs: 8000,
+  lockMs: 12000,
+  observeInvisible: true,
+  observePayments: true,
+  observeQuotes: true,
+  observeFlood: true,
+  editNotice: false,
+  observeReceipts: true,
+  receiptBurst: 6,
+  immunity: [],
+  historyLimit: 100
+})
+
+const GROUP_SUFFIX = '@g.us'
+const MAX_MONITORS = 3
+const MAX_SEEN = 6000
+const SEEN_TTL = 120000
+
+// Compara apenas o mesmo domínio de JID: PN e LID não são intercambiáveis.
+const canonicalJid = jid => {
+  if (typeof jid !== 'string' || !jid.includes('@')) return ''
+  const [user, domain] = jid.split('@')
+  return user.split(':')[0] + '@' + domain.toLowerCase()
+}
+const sameUser = (a, b) => !!canonicalJid(a) && canonicalJid(a) === canonicalJid(b)
+const isImmune = (identity, list) => Array.isArray(list) && list.some(jid => sameUser(jid, identity))
+const STORE_PREFIX = 'stone:groupProtection:'
+const storedSettings = settings => Object.fromEntries(Object.keys(DEFAULTS).map(key => [key, settings[key]]))
+const recordSafe = event => ({
+  jid: event.jid, participant: event.participant || null,
+  reason: event.reason || null, severity: event.severity || null,
+  action: event.action || null, mode: event.mode || event.attemptedMode || null,
+  deleted: !!event.deleted, removed: !!event.removed, locked: !!event.locked,
+  receivedAt: event.receivedAt || Date.now()
+})
+const isAdmin = p => !!p?.admin
+const boundedInt = (v, min, max, key) => {
+  if (!Number.isInteger(v) || v < min || v > max) {
+    throw new RangeError(`${key} deve ser um inteiro entre ${min} e ${max}`)
+  }
+  return v
+}
+
+function scanPayment(root) {
+  if (!root || typeof root !== 'object') return null
+  const seen = new WeakSet()
+  const todo = [{ node: root, depth: 0 }]
+  let checked = 0
+  while (todo.length && checked++ < 180) {
+    const { node, depth } = todo.pop()
+    if (!node || typeof node !== 'object' || seen.has(node) || depth > 7) continue
+    seen.add(node)
+    for (const [key, value] of Object.entries(node)) {
+      if (!value || key === 'quotedMessage') continue
+      if (PAYMENT_FIELDS.has(key)) return key
+      if (key === 'nativeFlowMessage' && Array.isArray(value.buttons)) {
+        for (const button of value.buttons) {
+          if (PAYMENT_BUTTONS.has(String(button?.name || '').toLowerCase())) return 'nativeFlowPayment'
+        }
+      }
+      if (typeof value === 'object') todo.push({ node: value, depth: depth + 1 })
+    }
+  }
+  return null
+}
+
+function findQuoted(root) {
+  let message = root
+  for (let i = 0; i < 5 && message && typeof message === 'object'; i++) {
+    for (const key of ['extendedTextMessage', 'imageMessage', 'videoMessage', 'documentMessage', 'buttonsResponseMessage', 'templateButtonReplyMessage']) {
+      const context = message[key]?.contextInfo
+      if (context?.quotedMessage) return { message: context.quotedMessage, participant: context.participant, stanzaId: context.stanzaId }
+    }
+    message = message.ephemeralMessage?.message || message.viewOnceMessage?.message || message.viewOnceMessageV2?.message || message.documentWithCaptionMessage?.message
+  }
+  return null
+}
+
+/** Instala proteção opcional em um socket sem alterar a recepção nativa. */
+export function createGroupProtectionMethods(socket) {
+  const groups = new Map()
+  const observers = new Map()
+  const seen = new Map()
+  const buckets = new Map()
+  const busy = new Set()
+  const recentActions = new Map()
+  const locks = new Map()
+  const persistence = new Map()
+  const managed = new Map()
+
+  function markOnce(key) {
+    const now = Date.now()
+    if (seen.has(key) && now - seen.get(key) < SEEN_TTL) return false
+    seen.set(key, now)
+    if (seen.size > MAX_SEEN) {
+      for (const [k, t] of seen) if (now - t >= SEEN_TTL) seen.delete(k)
+      while (seen.size > MAX_SEEN) seen.delete(seen.keys().next().value)
+    }
+    return true
+  }
+
+  function count(group, participant, kind, windowMs, mark) {
+    const key = `${group}\u0000${participant}\u0000${kind}`
+    const now = Date.now()
+    const old = (buckets.get(key) || []).filter(item => now - item.at < windowMs)
+    if (mark && !old.some(item => item.id === mark)) old.push({ id: mark, at: now })
+    buckets.set(key, old.slice(-80))
+    if (buckets.size > 3000) {
+      for (const [k, entries] of buckets) {
+        if (!entries.length || now - entries[entries.length - 1].at > 2 * windowMs) buckets.delete(k)
+      }
+    }
+    return old.length
+  }
+
+  function appendHistory(state, type, incident) {
+    const entry = { type, ...recordSafe(incident) }
+    state.history.push(entry)
+    if (state.history.length > state.settings.historyLimit) state.history.splice(0, state.history.length - state.settings.historyLimit)
+    if (state.store) {
+      const key = STORE_PREFIX + 'history:' + entry.jid
+      const previous = persistence.get(key) || Promise.resolve()
+      const task = previous.catch(() => {}).then(async () => {
+        await state.store.set(key, state.history.slice())
+      })
+      persistence.set(key, task)
+      task.catch(error => socket.logger?.warn?.({ error }, 'groupProtection history save failed'))
+    }
+  }
+  function emit(name, data) {
+    const state = groups.get(data?.jid)
+    if (state && (name === 'group-protection.alert' || name === 'group-protection.action')) {
+      appendHistory(state, name.endsWith('.alert') ? 'alert' : 'action', data)
+    }
+    try { socket.ev.emit(name, data) } catch (error) {
+      socket.logger?.warn?.({ error }, 'groupProtection event handler failed')
+    }
+  }
+
+  async function act(incident, message) {
+    const state = groups.get(incident.jid)
+    if (!state || state.settings.mode === 'alert' || incident.severity !== 'high' || !incident.verified) return
+    const lockKey = `${incident.jid}\u0000${incident.participant}`
+    if (busy.has(lockKey) || Date.now() - (recentActions.get(lockKey) || 0) < 30000) return
+    busy.add(lockKey)
+    recentActions.set(lockKey, Date.now())
+    if (recentActions.size > 3000) {
+      for (const [key, at] of recentActions) if (Date.now() - at > 60000) recentActions.delete(key)
+    }
+    const result = { ...incident, attemptedMode: state.settings.mode, deleted: false, removed: false, locked: false }
+    let notice = null
+    try {
+      const metadata = await socket.groupMetadata(incident.jid)
+      const members = Array.isArray(metadata?.participants) ? metadata.participants : []
+      const self = members.find(p => sameUser(p.id, socket.user?.id) || sameUser(p.id, socket.authState?.creds?.me?.lid))
+      const actor = members.find(p => sameUser(p.id, incident.participant))
+      if (!isAdmin(self)) {
+        result.error = 'bot_not_admin'
+        return
+      }
+      if (!actor || isAdmin(actor) || sameUser(actor.id, self.id)) {
+        result.error = 'target_unverified_or_admin'
+        return
+      }
+      if (isImmune(actor.id, state.settings.immunity)
+        || isImmune(actor.phoneNumber, state.settings.immunity)
+        || isImmune(actor.lid, state.settings.immunity)
+        || isImmune(incident.participant, state.settings.immunity)) {
+        result.error = 'immune_participant'
+        return
+      }
+      if (state.settings.editNotice) {
+        try {
+          notice = await socket.sendMessage(incident.jid, { text: 'Stone Protection: ameaça identificada. Verificando e aplicando as ações de moderação...' })
+        } catch (error) { result.noticeError = String(error?.message || error) }
+      }
+      if (state.settings.mode === 'protect' && !metadata.announce && !locks.has(incident.jid)) {
+        try {
+          await socket.groupSettingUpdate(incident.jid, 'announcement')
+          result.locked = true
+          const timer = setTimeout(async () => {
+            locks.delete(incident.jid)
+            try {
+              const latest = await socket.groupMetadata(incident.jid)
+              if (latest?.announce === true) await socket.groupSettingUpdate(incident.jid, 'not_announcement')
+            }
+            catch (error) { emit('group-protection.action', { jid: incident.jid, action: 'reopen', ok: false, error: String(error?.message || error) }) }
+          }, state.settings.lockMs)
+          timer.unref?.()
+          locks.set(incident.jid, timer)
+        } catch (error) { result.lockError = String(error?.message || error) }
+      }
+      if (message?.key?.id && message.key.remoteJid === incident.jid) {
+        try {
+          await socket.sendMessage(incident.jid, { delete: message.key })
+          result.deleted = true
+        } catch (error) { result.deleteError = String(error?.message || error) }
+      }
+      if (state.settings.mode === 'remove' || state.settings.mode === 'protect') {
+        try {
+          const response = await socket.groupParticipantsUpdate(incident.jid, [actor.id], 'remove')
+          result.removed = Array.isArray(response) && response.some(r => String(r.status) === '200')
+        } catch (error) { result.removeError = String(error?.message || error) }
+      }
+    } catch (error) { result.error = String(error?.message || error) }
+    finally {
+      if (notice?.key?.id && notice.key.fromMe === true) {
+        const status = result.removed ? 'participante removido' : result.deleted ? 'mensagem removida' : 'ações parciais ou indisponíveis'
+        try {
+          await socket.sendMessage(incident.jid, {
+            text: `Stone Protection: verificação concluída — ${status}.`,
+            edit: notice.key
+          })
+          result.noticeEdited = true
+        } catch (error) {
+          result.noticeEditError = String(error?.message || error)
+        }
+      }
+      busy.delete(lockKey)
+      state.actions++
+      emit('group-protection.action', result)
+    }
+  }
+
+  function report(incident, message) {
+    const state = groups.get(incident.jid)
+    if (!state) return
+    const evidenceKey = `${incident.jid}\u0000${incident.messageId}\u0000${incident.reason}\u0000${incident.participant}`
+    if (!markOnce(evidenceKey)) return
+    state.alerts++
+    emit('group-protection.alert', { ...incident, mode: state.settings.mode, receivedAt: Date.now() })
+    void act(incident, message).catch(error => socket.logger?.warn?.({ error }, 'groupProtection action failed'))
+  }
+
+  function handleSignal(data, source) {
+    if (!data?.remoteJid?.endsWith(GROUP_SUFFIX) || !data.messageId) return
+    const state = groups.get(data.remoteJid)
+    if (!state?.settings.observeInvisible) return
+    const actor = data.participant || data.participantAlt
+    if (!actor) return
+    const signature = String(data.decryptFail || '').toLowerCase()
+    const highSignal = signature === 'hide'
+    if (!markOnce(`signal\u0000${data.remoteJid}\u0000${data.messageId}\u0000${actor}`)) return
+    const hits = count(data.remoteJid, actor, 'ciphertext', state.settings.windowMs, data.messageId)
+    // Ciphertext não é prova de ataque; nunca punir só por falha de descriptografia.
+    if (highSignal || hits >= state.settings.paymentBurst) {
+      report({ jid: data.remoteJid, participant: actor, messageId: data.messageId, reason: 'invisible-suspected', severity: highSignal ? 'medium' : 'low', verified: false, source, evidence: { decryptFail: signature || null, ciphertextCount: hits } })
+    }
+  }
+
+  // Recibos são somente telemetria: pedidos de retransmissão são normais
+  // em redes instáveis e NÃO identificam culpabilidade de um participante.
+  function handleReceipt(data, source) {
+    if (!data?.remoteJid?.endsWith(GROUP_SUFFIX) || !data.messageId || !data.participant) return
+    const state = groups.get(data.remoteJid)
+    if (!state?.settings.observeReceipts || data.type !== 'retry') return
+    const mark = `receipt\u0000${data.remoteJid}\u0000${data.messageId}\u0000${data.participant}`
+    if (!markOnce(mark)) return
+    const n = count(data.remoteJid, data.participant, 'retry-receipt', state.settings.windowMs, data.messageId)
+    if (n === state.settings.receiptBurst || (n > state.settings.receiptBurst && n % state.settings.receiptBurst === 0)) {
+      report({ jid: data.remoteJid, participant: data.participant,
+        messageId: data.messageId, reason: 'receipt-suspected', severity: 'low',
+        verified: false, source, evidence: { type: data.type, receiptCount: n } })
+    }
+  }
+
+  function handlePdo(data, source) {
+    if (!data?.remoteJid?.endsWith(GROUP_SUFFIX)) return
+    const state = groups.get(data.remoteJid)
+    if (!state?.settings.observeInvisible || !data.messageId) return
+    emit('group-protection.pdo-observed', {
+      jid: data.remoteJid, messageId: data.messageId,
+      status: data.status, source, receivedAt: Date.now()
+    })
+  }
+
+  function handleMessage(message, source, kind = 'notify') {
+    const jid = message?.key?.remoteJid
+    if (!jid?.endsWith(GROUP_SUFFIX) || message.key.fromMe) return
+    const state = groups.get(jid)
+    if (!state || (kind !== 'notify' && kind !== 'append')) return
+    const id = message.key.id
+    const participant = message.key.participant || message.participant || message.key.participantAlt
+    if (!id || !participant || !message.message) return
+    const stamp = Number(message.messageTimestamp || 0)
+    if (stamp && Math.abs(Date.now() - stamp * 1000) > 120000) return
+    if (!markOnce(`message\u0000${jid}\u0000${id}`)) return
+    const settings = state.settings
+    const paymentType = settings.observePayments ? scanPayment(message.message) : null
+    const volume = settings.observeFlood ? count(jid, participant, 'messages', settings.windowMs, id) : 0
+    if (paymentType) {
+      const payments = count(jid, participant, 'payment', settings.windowMs, id)
+      report({ jid, participant, messageId: id, reason: 'payment', severity: payments >= settings.paymentBurst ? 'high' : 'low', verified: payments >= settings.paymentBurst, source, evidence: { paymentType, paymentCount: payments } }, message)
+    }
+    if (settings.observeFlood && volume >= settings.messageBurst) {
+      report({ jid, participant, messageId: id, reason: 'flood', severity: 'high', verified: true, source, evidence: { messageCount: volume } }, message)
+    }
+    // Citações são evidência auxiliar, nunca prova para punir outro participante.
+    if (settings.observeQuotes) {
+      const quoted = findQuoted(message.message)
+      const quotePayment = quoted && scanPayment(quoted.message)
+      if (quotePayment) {
+        report({ jid, participant: quoted.participant || participant, messageId: quoted.stanzaId || id, reason: 'quoted-payment', severity: 'medium', verified: false, source, evidence: { quotedBy: participant, paymentType: quotePayment } })
+      }
+    }
+  }
+
+  function connectObserver(monitor, index) {
+    if (!monitor?.ev || typeof monitor.ev.on !== 'function') throw new TypeError('monitor deve ser um socket Stone WPP conectado')
+    if (observers.has(monitor)) return
+    const source = index === -1 ? 'primary' : `monitor-${index + 1}`
+    const allowed = groupJid => monitor === socket || groups.get(groupJid)?.monitors.includes(monitor)
+    const onUpsert = payload => {
+      for (const message of payload?.messages || []) {
+        if (allowed(message?.key?.remoteJid)) handleMessage(message, source, payload?.type)
+      }
+    }
+    const onSignal = payload => {
+      if (allowed(payload?.remoteJid)) handleSignal(payload, source)
+    }
+    monitor.ev.on('messages.upsert', onUpsert)
+    const onReceipt = payload => {
+      if (allowed(payload?.remoteJid)) handleReceipt(payload, source)
+    }
+    const onPdo = payload => {
+      if (allowed(payload?.remoteJid)) handlePdo(payload, source)
+    }
+    monitor.ev.on('group-protection.ciphertext', onSignal)
+    monitor.ev.on('group-protection.receipt', onReceipt)
+    monitor.ev.on('group-protection.pdo', onPdo)
+    observers.set(monitor, () => {
+      monitor.ev.off('messages.upsert', onUpsert)
+      monitor.ev.off('group-protection.ciphertext', onSignal)
+      monitor.ev.off('group-protection.receipt', onReceipt)
+      monitor.ev.off('group-protection.pdo', onPdo)
+    })
+  }
+
+  function pruneObservers() {
+    const active = new Set([...groups.values()].flatMap(g => g.monitors))
+    for (const [monitor, detach] of observers) {
+      if (monitor !== socket && !active.has(monitor)) { detach(); observers.delete(monitor) }
+    }
+  }
+  function statusFor(jid, state, extra = {}) {
+    if (!state) return { jid, enabled: false, monitorCount: 0, alerts: 0, actions: 0, ...extra }
+    return { jid, ...state.settings, monitorCount: state.monitors.length,
+      alerts: state.alerts, actions: state.actions, ...extra }
+  }
+  function stopManaged(jid) {
+    for (const [key, active] of managed) {
+      if (!key.startsWith(jid + '\u0000')) continue
+      active.cancelled = true
+      if (active.timer) clearTimeout(active.timer)
+      if (active.socket && active.onUpdate) active.socket.ev.off('connection.update', active.onUpdate)
+      managed.delete(key)
+    }
+  }
+  async function startManaged(jid, index, factory, state, reconnectMs) {
+    const key = jid + '\u0000' + index
+    if (managed.get(key)?.factory === factory) return
+    const current = managed.get(key)
+    if (current) {
+      current.cancelled = true
+      if (current.timer) clearTimeout(current.timer)
+      if (current.socket && current.onUpdate) current.socket.ev.off('connection.update', current.onUpdate)
+    }
+    const item = { factory, timer: null, socket: null, onUpdate: null, attempt: 0, cancelled: false }
+    managed.set(key, item)
+    const attach = async () => {
+      if (item.cancelled || groups.get(jid) !== state) return
+      item.attempt++
+      try {
+        const create = typeof factory === 'function' ? factory : factory.create
+        const monitor = await create({ jid, attempt: item.attempt })
+        if (!monitor?.ev || typeof monitor.ev.on !== 'function' || monitor === socket) {
+          throw new TypeError('monitorFactory deve retornar outro socket autenticado')
+        }
+        if (item.cancelled || groups.get(jid) !== state) return
+        // Pareamento autorizado: o proprietário recebe o código via callback.
+        // Nenhuma sessão é vinculada sem a confirmação no próprio WhatsApp.
+        if (typeof factory === 'object' && factory.phoneNumber
+          && monitor.authState?.creds?.registered === false) {
+          if (typeof monitor.requestPairingCode !== 'function') {
+            throw new TypeError('socket auxiliar não suporta requestPairingCode')
+          }
+          const code = await monitor.requestPairingCode(factory.phoneNumber)
+          await factory.onPairingCode({ jid, index, code })
+        }
+        if (item.socket && item.onUpdate) item.socket.ev.off('connection.update', item.onUpdate)
+        const previous = item.socket
+        item.socket = monitor
+        if (previous) {
+          state.monitors = state.monitors.filter(m => m !== previous)
+        }
+        if (!state.monitors.includes(monitor)) state.monitors.push(monitor)
+        connectObserver(monitor, index)
+        pruneObservers()
+        item.onUpdate = update => {
+          if (update?.connection === 'open') {
+            item.attempt = 0
+            emit('group-protection.monitor', { jid, index, status: 'connected' })
+          }
+          if (update?.connection !== 'close' || item.cancelled) return
+          const code = update?.lastDisconnect?.error?.output?.statusCode
+          // Logged out: é necessário parear novamente com consentimento.
+          if (code === 401) {
+            monitor.ev.off('connection.update', item.onUpdate)
+            state.monitors = state.monitors.filter(m => m !== monitor)
+            item.socket = null
+            pruneObservers()
+            emit('group-protection.monitor', { jid, index, status: 'logged-out' })
+            return
+          }
+          monitor.ev.off('connection.update', item.onUpdate)
+          state.monitors = state.monitors.filter(m => m !== monitor)
+          pruneObservers()
+          schedule()
+        }
+        monitor.ev.on('connection.update', item.onUpdate)
+        emit('group-protection.monitor', { jid, index, status: 'attached' })
+      } catch (error) {
+        emit('group-protection.monitor', { jid, index, status: 'error',
+          error: String(error?.message || error) })
+        schedule()
+      }
+    }
+    const schedule = () => {
+      if (item.cancelled || groups.get(jid) !== state) return
+      const ms = Math.min(60000, reconnectMs * Math.pow(2, Math.min(item.attempt - 1, 5)))
+      item.timer = setTimeout(() => { item.timer = null; void attach() }, ms)
+      item.timer.unref?.()
+    }
+    await attach()
+  }
+
+  connectObserver(socket, -1)
+
+  return {
+    /**
+     * Consulta / configura a proteção. Monitors: sockets Stone extras autenticados
+     * separadamente e presentes nos mesmos grupos (até três). A Stone não cria sessões
+     * extras automaticamente nem promete acessar mensagens omitidas pelo WhatsApp.
+     */
+    async groupProtection(jid, options) {
+      if (typeof jid !== 'string' || !jid.endsWith(GROUP_SUFFIX)) {
+        throw new TypeError('groupProtection requer JID de grupo (@g.us)')
+      }
+      const old = groups.get(jid)
+      if (options === undefined) return statusFor(jid, old)
+      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('options deve ser um objeto')
+      }
+      const store = options.store || old?.store
+      if (store && (typeof store.get !== 'function' || typeof store.set !== 'function')) {
+        throw new TypeError('store requer métodos get e set')
+      }
+      if (options.getHistory === true) {
+        const limit = options.limit === undefined ? 100 : boundedInt(options.limit, 1, 500, 'limit')
+        const saved = store ? await store.get(STORE_PREFIX + 'history:' + jid) : null
+        const history = old?.history?.length ? old.history : (Array.isArray(saved) ? saved : [])
+        return statusFor(jid, old, { history: history.slice(-limit) })
+      }
+      if (options.enabled === false) {
+        const savedStore = store
+        groups.delete(jid)
+        stopManaged(jid)
+        pruneObservers()
+        if (savedStore) {
+          await savedStore.set(STORE_PREFIX + 'settings:' + jid, { enabled: false })
+        }
+        return statusFor(jid, null)
+      }
+      let restored = null
+      if (options.restore === true) {
+        if (!store) throw new TypeError('restore requer store')
+        restored = await store.get(STORE_PREFIX + 'settings:' + jid)
+        if (!restored?.enabled) return statusFor(jid, old, { restored: false })
+      }
+      const input = { ...(old?.settings || DEFAULTS), ...(restored || {}), ...options, enabled: true }
+      if (!['alert', 'delete', 'remove', 'protect'].includes(input.mode)) {
+        throw new TypeError('mode: alert, delete, remove ou protect')
+      }
+      for (const key of ['observeInvisible', 'observePayments', 'observeQuotes', 'observeFlood', 'editNotice', 'observeReceipts']) {
+        if (typeof input[key] !== 'boolean') throw new TypeError(`${key} deve ser booleano`)
+      }
+      input.paymentBurst = boundedInt(input.paymentBurst, 2, 30, 'paymentBurst')
+      input.messageBurst = boundedInt(input.messageBurst, 3, 100, 'messageBurst')
+      input.receiptBurst = boundedInt(input.receiptBurst, 3, 50, 'receiptBurst')
+      input.windowMs = boundedInt(input.windowMs, 1000, 60000, 'windowMs')
+      input.lockMs = boundedInt(input.lockMs, 3000, 120000, 'lockMs')
+      input.historyLimit = boundedInt(input.historyLimit, 20, 500, 'historyLimit')
+      if (!Array.isArray(input.immunity) || input.immunity.length > 200
+        || !input.immunity.every(jid => typeof jid === 'string' && canonicalJid(jid))) {
+        throw new TypeError('immunity deve conter até 200 JIDs válidos')
+      }
+      input.immunity = [...new Set(input.immunity.map(canonicalJid))]
+      const staticMonitors = options.monitors === undefined ? (old?.staticMonitors || []) : options.monitors
+      const factories = options.monitorFactories === undefined ? (old?.factories || []) : options.monitorFactories
+      if (!Array.isArray(staticMonitors) || !Array.isArray(factories)
+        || staticMonitors.length + factories.length > MAX_MONITORS
+        || new Set(staticMonitors).size !== staticMonitors.length || staticMonitors.includes(socket)
+        || !factories.every(f => typeof f === 'function' ||
+          (f && typeof f === 'object' && typeof f.create === 'function'
+          && (!f.phoneNumber || (typeof f.phoneNumber === 'string'
+          && /^\d{8,15}$/.test(f.phoneNumber)
+          && typeof f.onPairingCode === 'function'))))) {
+        throw new TypeError('Até 3 monitores: sockets distintos e/ou monitorFactories')
+      }
+      for (const monitor of staticMonitors) {
+        if (!monitor?.ev || typeof monitor.ev.on !== 'function') {
+          throw new TypeError('monitor deve ser socket Stone válido')
+        }
+      }
+      const reconnectMs = options.monitorReconnectMs === undefined
+        ? (old?.monitorReconnectMs || 3000)
+        : boundedInt(options.monitorReconnectMs, 1000, 60000, 'monitorReconnectMs')
+      const settings = storedSettings(input)
+      const state = old || { alerts: 0, actions: 0, history: [], monitors: [] }
+      state.settings = settings
+      state.staticMonitors = staticMonitors
+      state.factories = factories
+      state.monitorReconnectMs = reconnectMs
+      state.store = store
+      state.monitors = [...staticMonitors, ...[...managed.entries()]
+        .filter(([key, item]) => key.startsWith(jid + '\u0000')
+          && !item.cancelled && item.socket && factories.includes(item.factory))
+        .map(([, item]) => item.socket)]
+      if (store && !old?.history?.length) {
+        const history = await store.get(STORE_PREFIX + 'history:' + jid)
+        if (Array.isArray(history)) state.history = history.slice(-settings.historyLimit)
+      }
+      groups.set(jid, state)
+      staticMonitors.forEach((monitor, index) => connectObserver(monitor, index))
+      for (const [key, item] of managed) {
+        if (!key.startsWith(jid + '\u0000')) continue
+        const index = Number(key.slice((jid + '\u0000').length))
+        if (factories[index] !== item.factory) {
+          item.cancelled = true
+          if (item.timer) clearTimeout(item.timer)
+          if (item.socket && item.onUpdate) item.socket.ev.off('connection.update', item.onUpdate)
+          state.monitors = state.monitors.filter(monitor => monitor !== item.socket)
+          managed.delete(key)
+        }
+      }
+      for (let i = 0; i < factories.length; i++) {
+        await startManaged(jid, i, factories[i], state, reconnectMs)
+      }
+      pruneObservers()
+      if (store) {
+        await store.set(STORE_PREFIX + 'settings:' + jid, settings)
+      }
+      return statusFor(jid, state, { ...(options.restore ? { restored: true } : {}) })
+    }
+  }
+}

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('./stone-features.js').StoneAdditionalMethods & import('./group-protection.js').GroupProtectionMethods;
 export default makeWASocket;

package/lib/Socket/index.js

@@ -1,6 +1,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';
 // export the last socket layer
 const makeWASocket = (config) => {
     const newConfig = {
@@ -8,6 +9,6 @@ const makeWASocket = (config) => {
         ...config
     };
     const socket = makeCommunitiesSocket(newConfig);
-    return Object.assign(socket, createStoneAdditionalMethods(socket));
+    return Object.assign(socket, createStoneAdditionalMethods(socket), createGroupProtectionMethods(socket));
 };
 export default makeWASocket;

package/lib/Socket/messages-recv.js

@@ -37,6 +37,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 +73,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 +90,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 +1188,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 +1326,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 +1335,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');
                     }

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

@@ -2,6 +2,8 @@ import type { MiscMessageGenerationOptions, WAMessage, WAMessageKey } from '../T
 import type { Label } from '../Types/Label.js'
 
 export interface StoneAdditionalMethods {
+  /** Edita o texto de mensagem enviada pelo próprio bot; não edita mensagens de terceiros. */
+  editMessage(jid: string, messageKey: WAMessageKey, text: string): Promise<WAMessage | undefined>;
   /** Pesquisa username pelo USync. Não retorna números de telefone. */
   queryUsernameExists(username: string, pin?: string): Promise<{ username: string; jid: string; wid: string; exists: true } | null>;
   /** Cria ou altera uma nota da conta WhatsApp Business via app-state. */

package/lib/Socket/stone-features.js

@@ -57,6 +57,30 @@ export function createStoneAdditionalMethods(socket) {
   })
 
   return {
+    /**
+     * Edita uma mensagem enviada pela própria conta.
+     * A Stone já implementa MESSAGE_EDIT no sendMessage: aqui há um atalho
+     * com validação para não tentar falsificar mensagens de terceiros.
+     */
+    async editMessage(jid, messageKey, text) {
+      requireJid(jid)
+      if (!messageKey || typeof messageKey !== 'object' || !messageKey.id) {
+        throw new TypeError('Informe a chave (key) da mensagem enviada pelo bot')
+      }
+      if (messageKey.fromMe !== true) {
+        throw new TypeError('Só é possível editar mensagens enviadas pela própria conta')
+      }
+      if (messageKey.remoteJid && messageKey.remoteJid !== jid) {
+        throw new TypeError('A mensagem original não pertence a esta conversa')
+      }
+      if (typeof text !== 'string' || !text.trim()) {
+        throw new TypeError('Informe o novo texto da mensagem')
+      }
+      return socket.sendMessage(jid, {
+        text,
+        edit: { ...messageKey, remoteJid: jid, fromMe: true }
+      })
+    },
     /**
      * Consulta um @username pelo USync do WhatsApp, com PIN opcional.
      * Não revela nem infere o número de telefone.

package/lib/Types/Events.d.ts

@@ -10,6 +10,61 @@ import type { LabelAssociation } from './LabelAssociation.js';
 import type { MessageUpsertType, MessageUserReceiptUpdate, WAMessage, WAMessageKey, WAMessageUpdate } from './Message.js';
 import type { ConnectionState, NewChatMessageCapInfo } from './State.js';
 export type StoneWPPEventMap = {
+    /** Sinal da recepção nativa de ciphertext (não confirma ataque). */
+    'group-protection.ciphertext': {
+        remoteJid: string;
+        messageId: string;
+        participant: string;
+        participantAlt?: string;
+        decryptFail?: string | null;
+        encType?: string | null;
+        messageTimestamp?: number | bigint | object | null;
+        receivedAt: number;
+    };
+    /** Sinal da recepção nativa de ciphertext (não confirma ataque). */
+    'tokito.security.ciphertext': {
+        remoteJid: string;
+        messageId: string;
+        participant: string;
+        participantAlt?: string;
+        decryptFail?: string | null;
+        encType?: string | null;
+        messageTimestamp?: number | bigint | object | null;
+        receivedAt: number;
+    };
+    /** Proteção de grupos: alerta de anomalia ou flood. */
+    'group-protection.alert': import('../Socket/group-protection.js').GroupProtectionAlert;
+    /** Ação da proteção: resultado real da tentativa. */
+    'group-protection.action': import('../Socket/group-protection.js').GroupProtectionAction;
+    /** Recibo de retry de grupo, sem conteúdo e sem provar ataque. */
+    'group-protection.receipt': {
+        remoteJid: string;
+        messageId: string;
+        participant: string;
+        type: 'retry';
+        receivedAt: number;
+    };
+    /** Telemetria nativa do PDO de placeholder resend. */
+    'group-protection.pdo': {
+        remoteJid: string;
+        messageId: string;
+        status: 'requested' | 'resolved' | 'timeout';
+    };
+    /** Notificação filtrada de PDO de grupos monitorados. */
+    'group-protection.pdo-observed': {
+        jid: string;
+        messageId: string;
+        status: string;
+        source: string;
+        receivedAt: number;
+    };
+    /** Estado de sockets complementares gerenciados pela aplicação. */
+    'group-protection.monitor': {
+        jid: string;
+        index: number;
+        status: 'attached' | 'connected' | 'logged-out' | 'error';
+        error?: string;
+    };
     /** connection state has been updated -- WS closed, opened, connecting etc. */
     'connection.update': Partial<ConnectionState>;
     /** credentials updated -- some metadata, keys or something */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stone-wpp/ofc",
   "type": "module",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Stone WPP — biblioteca modular para WhatsApp em Node.js: conexão, mensagens, grupos, canais, armazenamento e extensões",
   "keywords": [
     "stone-wpp",
@@ -26,10 +26,13 @@
     "Protocol/**/*",
     "engine-requirements.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/**/*"
   ],
   "scripts": {
-    "preinstall": "node ./engine-requirements.js"
+    "preinstall": "node ./engine-requirements.js",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
   },
   "dependencies": {
     "@cacheable/node-cache": "^1.4.0",
@@ -95,6 +98,9 @@
     "node": ">=20.0.0"
   },
   "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dylan-Modz/stone-wpp-ofc.git"