@omnizap-system/omnizap 2.5.12

package/database/init.js

@@ -0,0 +1,151 @@
+import mysql from 'mysql2/promise';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import logger from '#logger';
+import { dbConfig } from './index.js';
+
+const dbToCreate = dbConfig.database;
+
+const createDatabaseSQL = `
+  CREATE DATABASE IF NOT EXISTS \`${dbToCreate}\`
+  DEFAULT CHARACTER SET utf8mb4
+  DEFAULT COLLATE utf8mb4_unicode_ci;
+`;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SCHEMA_SQL_PATH = path.join(__dirname, 'schema.sql');
+
+/**
+ * Divide um arquivo SQL em statements individuais.
+ * Suporta aspas simples e duplas para não quebrar strings.
+ *
+ * @param {string} sql
+ * @returns {string[]}
+ */
+function splitSqlStatements(sql) {
+  const statements = [];
+  let current = '';
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let escaped = false;
+
+  for (const char of sql) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      current += char;
+      escaped = true;
+      continue;
+    }
+
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      current += char;
+      continue;
+    }
+
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      current += char;
+      continue;
+    }
+
+    if (char === ';' && !inSingleQuote && !inDoubleQuote) {
+      const statement = current.trim();
+      if (statement) statements.push(statement);
+      current = '';
+      continue;
+    }
+
+    current += char;
+  }
+
+  const trailing = current.trim();
+  if (trailing) statements.push(trailing);
+
+  return statements;
+}
+
+/**
+ * Executa o schema consolidado para garantir que todas as tabelas existam.
+ *
+ * @param {import('mysql2/promise').Connection} connection
+ * @returns {Promise<number>} Quantidade de statements executados.
+ */
+async function runSchemaBootstrap(connection) {
+  let sqlContent = '';
+  try {
+    sqlContent = await fs.readFile(SCHEMA_SQL_PATH, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      const wrapped = new Error(`Arquivo de schema não encontrado em ${SCHEMA_SQL_PATH}.`);
+      wrapped.code = 'SCHEMA_SQL_NOT_FOUND';
+      throw wrapped;
+    }
+    throw error;
+  }
+
+  const statements = splitSqlStatements(sqlContent);
+  if (statements.length === 0) {
+    logger.warn('Arquivo schema.sql está vazio. Nenhuma tabela será criada.');
+    return 0;
+  }
+
+  for (const statement of statements) {
+    await connection.query(statement);
+  }
+
+  return statements.length;
+}
+
+/**
+ * Inicializa o banco de dados:
+ * 1) Conecta ao MySQL sem database
+ * 2) Cria o banco se não existir
+ * 3) Muda para o database correto
+ * 4) Executa o schema consolidado (sem migrations)
+ * 5) Encerra a conexão
+ *
+ * @returns {Promise<void>}
+ */
+export default async function initializeDatabase() {
+  let connection;
+
+  try {
+    connection = await mysql.createConnection({
+      host: dbConfig.host,
+      user: dbConfig.user,
+      password: dbConfig.password,
+    });
+
+    await connection.query(createDatabaseSQL);
+    logger.info(`Banco de dados '${dbToCreate}' verificado/criado com sucesso.`);
+
+    await connection.changeUser({ database: dbToCreate });
+
+    const executedStatements = await runSchemaBootstrap(connection);
+
+    logger.info('Schema consolidado verificado/aplicado com sucesso (sem migrations).', {
+      executedStatements,
+    });
+  } catch (error) {
+    logger.error(`Erro ao inicializar o banco: ${error.code || ''} ${error.message}`);
+    process.exit(1);
+  } finally {
+    if (connection) {
+      await connection.end();
+      logger.info('Conexão com o MySQL encerrada após inicialização.');
+    }
+  }
+}
+
+if (process.argv[1] === __filename) {
+  initializeDatabase();
+}

package/database/migrations/20260307_d0_hardening_down.sql

@@ -0,0 +1,64 @@
+-- D0 rollback
+-- Run with mysql client:
+--   mysql -u$DB_USER -p$DB_PASSWORD -h$DB_HOST $DB_NAME < database/migrations/20260307_d0_hardening_down.sql
+
+SET @migration_key := '20260307_d0_hardening';
+
+DROP PROCEDURE IF EXISTS __ensure_index;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;
+
+DELIMITER $$
+CREATE PROCEDURE __ensure_index(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __drop_index_if_exists(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64))
+BEGIN
+  IF EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = CONCAT('ALTER TABLE `', p_table_name, '` DROP INDEX `', p_index_name, '`');
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+DELIMITER ;
+
+-- Restore redundant indexes removed in D0
+CALL __ensure_index('sticker_pack_item', 'idx_sticker_pack_item_pack_position', 'CREATE INDEX idx_sticker_pack_item_pack_position ON sticker_pack_item (pack_id, position)');
+CALL __ensure_index('domain_event_outbox_dlq', 'idx_domain_event_outbox_dlq_outbox_event_id', 'CREATE INDEX idx_domain_event_outbox_dlq_outbox_event_id ON domain_event_outbox_dlq (outbox_event_id)');
+CALL __ensure_index('sticker_worker_task_dlq', 'idx_sticker_worker_task_dlq_task_id', 'CREATE INDEX idx_sticker_worker_task_dlq_task_id ON sticker_worker_task_dlq (task_id)');
+
+-- Drop indexes added in D0
+CALL __drop_index_if_exists('messages', 'idx_messages_sender_timestamp');
+CALL __drop_index_if_exists('messages', 'idx_messages_chat_sender_timestamp');
+CALL __drop_index_if_exists('domain_event_outbox', 'idx_domain_event_outbox_status_locked');
+CALL __drop_index_if_exists('email_outbox', 'idx_email_outbox_status_locked');
+CALL __drop_index_if_exists('sticker_worker_task_queue', 'idx_sticker_worker_task_queue_status_locked');
+CALL __drop_index_if_exists('sticker_asset_reprocess_queue', 'idx_sticker_asset_reprocess_queue_status_locked');
+
+UPDATE schema_change_log
+   SET status = 'rolled_back',
+       notes = 'D0 rollback executed',
+       updated_at = CURRENT_TIMESTAMP
+ WHERE migration_key = @migration_key;
+
+DROP PROCEDURE IF EXISTS __ensure_index;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;

package/database/migrations/20260307_d0_hardening_up.sql

@@ -0,0 +1,79 @@
+-- D0 (2026-03-07) - Non-breaking hardening
+-- Scope: indexes for queue reclaim/perf, remove redundant indexes, migration audit table
+-- Run with mysql client:
+--   mysql -u$DB_USER -p$DB_PASSWORD -h$DB_HOST $DB_NAME < database/migrations/20260307_d0_hardening_up.sql
+
+SET @migration_key := '20260307_d0_hardening';
+
+CREATE TABLE IF NOT EXISTS schema_change_log (
+  migration_key VARCHAR(128) NOT NULL,
+  phase VARCHAR(32) NOT NULL,
+  status ENUM('applied', 'rolled_back') NOT NULL DEFAULT 'applied',
+  notes VARCHAR(255) DEFAULT NULL,
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (migration_key),
+  KEY idx_schema_change_log_phase_status (phase, status, updated_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+DROP PROCEDURE IF EXISTS __ensure_index;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;
+
+DELIMITER $$
+CREATE PROCEDURE __ensure_index(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __drop_index_if_exists(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64))
+BEGIN
+  IF EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = CONCAT('ALTER TABLE `', p_table_name, '` DROP INDEX `', p_index_name, '`');
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+DELIMITER ;
+
+-- Performance indexes (non-breaking)
+CALL __ensure_index('messages', 'idx_messages_sender_timestamp', 'CREATE INDEX idx_messages_sender_timestamp ON messages (sender_id, timestamp)');
+CALL __ensure_index('messages', 'idx_messages_chat_sender_timestamp', 'CREATE INDEX idx_messages_chat_sender_timestamp ON messages (chat_id, sender_id, timestamp)');
+
+CALL __ensure_index('domain_event_outbox', 'idx_domain_event_outbox_status_locked', 'CREATE INDEX idx_domain_event_outbox_status_locked ON domain_event_outbox (status, locked_at)');
+CALL __ensure_index('email_outbox', 'idx_email_outbox_status_locked', 'CREATE INDEX idx_email_outbox_status_locked ON email_outbox (status, locked_at)');
+CALL __ensure_index('sticker_worker_task_queue', 'idx_sticker_worker_task_queue_status_locked', 'CREATE INDEX idx_sticker_worker_task_queue_status_locked ON sticker_worker_task_queue (status, locked_at)');
+CALL __ensure_index('sticker_asset_reprocess_queue', 'idx_sticker_asset_reprocess_queue_status_locked', 'CREATE INDEX idx_sticker_asset_reprocess_queue_status_locked ON sticker_asset_reprocess_queue (status, locked_at)');
+
+-- Remove redundant indexes (safe)
+CALL __drop_index_if_exists('sticker_pack_item', 'idx_sticker_pack_item_pack_position');
+CALL __drop_index_if_exists('domain_event_outbox_dlq', 'idx_domain_event_outbox_dlq_outbox_event_id');
+CALL __drop_index_if_exists('sticker_worker_task_dlq', 'idx_sticker_worker_task_dlq_task_id');
+
+INSERT INTO schema_change_log (migration_key, phase, status, notes)
+VALUES (@migration_key, 'D0', 'applied', 'Indexes hardening + redundant index cleanup')
+ON DUPLICATE KEY UPDATE
+  phase = VALUES(phase),
+  status = 'applied',
+  notes = VALUES(notes),
+  updated_at = CURRENT_TIMESTAMP;
+
+DROP PROCEDURE IF EXISTS __ensure_index;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;

package/database/migrations/20260307_d1_terms_acceptance_down.sql

@@ -0,0 +1,11 @@
+-- D1 rollback
+
+SET @migration_key := '20260307_d1_terms_acceptance';
+
+DROP TABLE IF EXISTS web_terms_acceptance_event;
+
+UPDATE schema_change_log
+   SET status = 'rolled_back',
+       notes = 'D1 rollback executado',
+       updated_at = CURRENT_TIMESTAMP
+ WHERE migration_key = @migration_key;

package/database/migrations/20260307_d1_terms_acceptance_up.sql

@@ -0,0 +1,37 @@
+-- D1 (2026-03-07) - Registro versionado de aceite juridico
+-- Scope: trilha probatoria de aceite de Termos/Politicas (hash da versao + timestamp + IP + user agent)
+
+SET @migration_key := '20260307_d1_terms_acceptance';
+
+CREATE TABLE IF NOT EXISTS web_terms_acceptance_event (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  event_id CHAR(36) NOT NULL,
+  document_key VARCHAR(64) NOT NULL,
+  document_version VARCHAR(64) NOT NULL,
+  document_version_hash CHAR(64) NOT NULL,
+  accepted_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  accepted_at_client TIMESTAMP NULL DEFAULT NULL,
+  source VARCHAR(32) NOT NULL DEFAULT 'web_login',
+  google_sub VARCHAR(80) DEFAULT NULL,
+  email VARCHAR(255) DEFAULT NULL,
+  owner_jid VARCHAR(120) DEFAULT NULL,
+  session_key VARCHAR(80) DEFAULT NULL,
+  ip_address VARCHAR(64) DEFAULT NULL,
+  user_agent VARCHAR(512) DEFAULT NULL,
+  metadata LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL CHECK (json_valid(metadata)),
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  UNIQUE KEY uq_web_terms_acceptance_event_id (event_id),
+  KEY idx_web_terms_acceptance_doc_version (document_key, document_version, accepted_at),
+  KEY idx_web_terms_acceptance_identity (google_sub, email, owner_jid, accepted_at),
+  KEY idx_web_terms_acceptance_source_created (source, created_at),
+  KEY idx_web_terms_acceptance_session_created (session_key, created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+INSERT INTO schema_change_log (migration_key, phase, status, notes)
+VALUES (@migration_key, 'D1', 'applied', 'Tabela de aceite versionado de termos/politicas')
+ON DUPLICATE KEY UPDATE
+  phase = VALUES(phase),
+  status = 'applied',
+  notes = VALUES(notes),
+  updated_at = CURRENT_TIMESTAMP;

package/database/migrations/20260307_d2_auth_hardening_down.sql

@@ -0,0 +1,75 @@
+-- D2 rollback
+
+SET @migration_key := '20260307_d2_auth_hardening';
+
+DROP PROCEDURE IF EXISTS __drop_column_if_exists;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;
+
+DELIMITER $$
+CREATE PROCEDURE __drop_column_if_exists(IN p_table_name VARCHAR(64), IN p_column_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF EXISTS (
+    SELECT 1
+      FROM information_schema.columns
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND column_name = p_column_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __drop_index_if_exists(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+DELIMITER ;
+
+CALL __drop_index_if_exists(
+  'web_user_password_recovery_code',
+  'idx_web_user_password_recovery_email_hash_created',
+  'DROP INDEX idx_web_user_password_recovery_email_hash_created ON web_user_password_recovery_code'
+);
+
+CALL __drop_column_if_exists(
+  'web_user_password_recovery_code',
+  'email_hash',
+  'ALTER TABLE web_user_password_recovery_code DROP COLUMN email_hash'
+);
+
+CALL __drop_column_if_exists(
+  'web_user_password_recovery_code',
+  'requested_ip_hash',
+  'ALTER TABLE web_user_password_recovery_code DROP COLUMN requested_ip_hash'
+);
+
+CALL __drop_column_if_exists(
+  'web_user_password_recovery_code',
+  'requested_user_agent_hash',
+  'ALTER TABLE web_user_password_recovery_code DROP COLUMN requested_user_agent_hash'
+);
+
+DROP TABLE IF EXISTS web_user_password_login_throttle;
+
+DROP PROCEDURE IF EXISTS __drop_column_if_exists;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;
+
+UPDATE schema_change_log
+   SET status = 'rolled_back',
+       notes = 'D2 rollback executado',
+       updated_at = CURRENT_TIMESTAMP
+ WHERE migration_key = @migration_key;

package/database/migrations/20260307_d2_auth_hardening_up.sql

@@ -0,0 +1,100 @@
+-- D2 (2026-03-07) - Auth hardening follow-up
+-- Scope: distributed login throttle + hashed sensitive metadata for password recovery
+
+SET @migration_key := '20260307_d2_auth_hardening';
+
+DROP PROCEDURE IF EXISTS __ensure_column;
+DROP PROCEDURE IF EXISTS __ensure_index;
+
+DELIMITER $$
+CREATE PROCEDURE __ensure_column(IN p_table_name VARCHAR(64), IN p_column_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM information_schema.columns
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND column_name = p_column_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __ensure_index(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+DELIMITER ;
+
+CREATE TABLE IF NOT EXISTS web_user_password_login_throttle (
+  identity_hash BINARY(32) NOT NULL,
+  failed_attempts SMALLINT UNSIGNED NOT NULL DEFAULT 0,
+  last_failed_at TIMESTAMP NULL DEFAULT NULL,
+  locked_until TIMESTAMP NULL DEFAULT NULL,
+  created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (identity_hash),
+  KEY idx_web_user_password_login_throttle_locked_until (locked_until),
+  KEY idx_web_user_password_login_throttle_failed (failed_attempts, last_failed_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CALL __ensure_column(
+  'web_user_password_recovery_code',
+  'email_hash',
+  'ALTER TABLE web_user_password_recovery_code ADD COLUMN email_hash BINARY(32) NULL AFTER email'
+);
+
+CALL __ensure_column(
+  'web_user_password_recovery_code',
+  'requested_ip_hash',
+  'ALTER TABLE web_user_password_recovery_code ADD COLUMN requested_ip_hash BINARY(32) NULL AFTER requested_ip'
+);
+
+CALL __ensure_column(
+  'web_user_password_recovery_code',
+  'requested_user_agent_hash',
+  'ALTER TABLE web_user_password_recovery_code ADD COLUMN requested_user_agent_hash BINARY(32) NULL AFTER requested_user_agent'
+);
+
+CALL __ensure_index(
+  'web_user_password_recovery_code',
+  'idx_web_user_password_recovery_email_hash_created',
+  'CREATE INDEX idx_web_user_password_recovery_email_hash_created ON web_user_password_recovery_code (email_hash, created_at)'
+);
+
+CALL __ensure_index(
+  'web_user_password_login_throttle',
+  'idx_web_user_password_login_throttle_locked_until',
+  'CREATE INDEX idx_web_user_password_login_throttle_locked_until ON web_user_password_login_throttle (locked_until)'
+);
+
+CALL __ensure_index(
+  'web_user_password_login_throttle',
+  'idx_web_user_password_login_throttle_failed',
+  'CREATE INDEX idx_web_user_password_login_throttle_failed ON web_user_password_login_throttle (failed_attempts, last_failed_at)'
+);
+
+DROP PROCEDURE IF EXISTS __ensure_column;
+DROP PROCEDURE IF EXISTS __ensure_index;
+
+INSERT INTO schema_change_log (migration_key, phase, status, notes)
+VALUES (@migration_key, 'D2', 'applied', 'Distributed login throttle + hashed recovery sensitive metadata')
+ON DUPLICATE KEY UPDATE
+  phase = VALUES(phase),
+  status = 'applied',
+  notes = VALUES(notes),
+  updated_at = CURRENT_TIMESTAMP;

package/database/migrations/20260314_d7_canonical_sender_down.sql

@@ -0,0 +1,53 @@
+-- D+7 rollback
+
+SET @migration_key := '20260314_d7_canonical_sender';
+
+DROP PROCEDURE IF EXISTS __drop_column_if_exists;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;
+
+DELIMITER $$
+CREATE PROCEDURE __drop_column_if_exists(IN p_table_name VARCHAR(64), IN p_column_name VARCHAR(64))
+BEGIN
+  IF EXISTS (
+    SELECT 1
+      FROM information_schema.columns
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND column_name = p_column_name
+  ) THEN
+    SET @ddl = CONCAT('ALTER TABLE `', p_table_name, '` DROP COLUMN `', p_column_name, '`');
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __drop_index_if_exists(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64))
+BEGIN
+  IF EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = CONCAT('ALTER TABLE `', p_table_name, '` DROP INDEX `', p_index_name, '`');
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+DELIMITER ;
+
+CALL __drop_index_if_exists('messages', 'idx_messages_chat_canonical_sender_timestamp');
+CALL __drop_index_if_exists('messages', 'idx_messages_canonical_sender_timestamp');
+CALL __drop_column_if_exists('messages', 'canonical_sender_id');
+
+UPDATE schema_change_log
+   SET status = 'rolled_back',
+       notes = 'D+7 rollback executed',
+       updated_at = CURRENT_TIMESTAMP
+ WHERE migration_key = @migration_key;
+
+DROP PROCEDURE IF EXISTS __drop_column_if_exists;
+DROP PROCEDURE IF EXISTS __drop_index_if_exists;

package/database/migrations/20260314_d7_canonical_sender_up.sql

@@ -0,0 +1,114 @@
+-- D+7 (2026-03-14) - Small migration
+-- Scope: canonical sender column for high-volume ranking/analytics queries
+
+SET @migration_key := '20260314_d7_canonical_sender';
+
+DROP PROCEDURE IF EXISTS __ensure_column;
+DROP PROCEDURE IF EXISTS __drop_column_if_exists;
+DROP PROCEDURE IF EXISTS __ensure_index;
+DROP PROCEDURE IF EXISTS __backfill_messages_canonical_sender;
+
+DELIMITER $$
+CREATE PROCEDURE __ensure_column(IN p_table_name VARCHAR(64), IN p_column_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM information_schema.columns
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND column_name = p_column_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __drop_column_if_exists(IN p_table_name VARCHAR(64), IN p_column_name VARCHAR(64))
+BEGIN
+  IF EXISTS (
+    SELECT 1
+      FROM information_schema.columns
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND column_name = p_column_name
+  ) THEN
+    SET @ddl = CONCAT('ALTER TABLE `', p_table_name, '` DROP COLUMN `', p_column_name, '`');
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __ensure_index(IN p_table_name VARCHAR(64), IN p_index_name VARCHAR(64), IN p_ddl TEXT)
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM information_schema.statistics
+     WHERE table_schema = DATABASE()
+       AND table_name = p_table_name
+       AND index_name = p_index_name
+  ) THEN
+    SET @ddl = p_ddl;
+    PREPARE stmt FROM @ddl;
+    EXECUTE stmt;
+    DEALLOCATE PREPARE stmt;
+  END IF;
+END$$
+
+CREATE PROCEDURE __backfill_messages_canonical_sender(IN p_batch_size BIGINT UNSIGNED)
+BEGIN
+  DECLARE v_min BIGINT UNSIGNED DEFAULT 0;
+  DECLARE v_max BIGINT UNSIGNED DEFAULT 0;
+  DECLARE v_cursor BIGINT UNSIGNED DEFAULT 0;
+
+  SELECT COALESCE(MIN(id), 0), COALESCE(MAX(id), 0)
+    INTO v_min, v_max
+    FROM messages
+   WHERE canonical_sender_id IS NULL;
+
+  SET v_cursor = v_min;
+
+  WHILE v_cursor > 0 AND v_cursor <= v_max DO
+    UPDATE messages m
+    LEFT JOIN lid_map lm
+      ON lm.lid = m.sender_id
+     AND lm.jid IS NOT NULL
+       SET m.canonical_sender_id = COALESCE(lm.jid, m.sender_id)
+     WHERE m.id BETWEEN v_cursor AND (v_cursor + p_batch_size - 1)
+       AND m.canonical_sender_id IS NULL;
+
+    SET v_cursor = v_cursor + p_batch_size;
+  END WHILE;
+END$$
+DELIMITER ;
+
+CALL __ensure_column('messages', 'canonical_sender_id', 'ALTER TABLE messages ADD COLUMN canonical_sender_id VARCHAR(255) NULL AFTER sender_id');
+
+CALL __ensure_index('messages', 'idx_messages_canonical_sender_timestamp', 'CREATE INDEX idx_messages_canonical_sender_timestamp ON messages (canonical_sender_id, timestamp)');
+CALL __ensure_index('messages', 'idx_messages_chat_canonical_sender_timestamp', 'CREATE INDEX idx_messages_chat_canonical_sender_timestamp ON messages (chat_id, canonical_sender_id, timestamp)');
+
+-- Backfill in chunks (adjust batch size according to table size / write pressure)
+CALL __backfill_messages_canonical_sender(50000);
+
+-- Safety pass for rows inserted during chunk loop
+UPDATE messages m
+LEFT JOIN lid_map lm
+  ON lm.lid = m.sender_id
+ AND lm.jid IS NOT NULL
+   SET m.canonical_sender_id = COALESCE(lm.jid, m.sender_id)
+ WHERE m.canonical_sender_id IS NULL;
+
+INSERT INTO schema_change_log (migration_key, phase, status, notes)
+VALUES (@migration_key, 'D+7', 'applied', 'messages.canonical_sender_id + backfill + indexes')
+ON DUPLICATE KEY UPDATE
+  phase = VALUES(phase),
+  status = 'applied',
+  notes = VALUES(notes),
+  updated_at = CURRENT_TIMESTAMP;
+
+DROP PROCEDURE IF EXISTS __ensure_column;
+DROP PROCEDURE IF EXISTS __drop_column_if_exists;
+DROP PROCEDURE IF EXISTS __ensure_index;
+DROP PROCEDURE IF EXISTS __backfill_messages_canonical_sender;