@omnizap-system/omnizap 2.5.12

package/server/auth/userPassword/userPasswordAuthService.js

@@ -0,0 +1,422 @@
+import { hashUserPassword, resolveUserPasswordPolicy, validateUserPassword, verifyUserPasswordHash } from './userPasswordCrypto.js';
+
+const clampInt = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const normalizeGoogleSubject = (value) =>
+  String(value || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9_-]/g, '')
+    .slice(0, 80);
+
+const normalizeEmail = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .slice(0, 255);
+
+const normalizeJid = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .slice(0, 255);
+
+const normalizeName = (value) =>
+  String(value || '')
+    .trim()
+    .slice(0, 120) || null;
+
+const toIsoOrNull = (value) => {
+  const timestamp = Number(new Date(value || 0));
+  if (!Number.isFinite(timestamp) || timestamp <= 0) return null;
+  return new Date(timestamp).toISOString();
+};
+
+const buildHttpError = (message, { statusCode = 400, code = 'BAD_REQUEST' } = {}) => {
+  const error = new Error(String(message || 'Erro interno.'));
+  error.statusCode = Number(statusCode) || 400;
+  error.code = String(code || 'BAD_REQUEST');
+  return error;
+};
+
+const normalizeIdentity = ({ googleSub = '', email = '', ownerJid = '' } = {}) => {
+  const normalizedGoogleSub = normalizeGoogleSubject(googleSub);
+  const normalizedEmail = normalizeEmail(email);
+  const normalizedOwnerJid = normalizeJid(ownerJid);
+  return {
+    googleSub: normalizedGoogleSub,
+    email: normalizedEmail,
+    ownerJid: normalizedOwnerJid,
+    hasIdentity: Boolean(normalizedGoogleSub || normalizedEmail || normalizedOwnerJid),
+  };
+};
+
+const buildIdentityFilterClause = ({ googleSub = '', email = '', ownerJid = '' } = {}, tableAlias = 'u') => {
+  const clauses = [];
+  const params = [];
+
+  if (googleSub) {
+    clauses.push(`${tableAlias}.google_sub = ?`);
+    params.push(googleSub);
+  }
+
+  if (email) {
+    clauses.push(`${tableAlias}.email = ?`);
+    params.push(email);
+  }
+
+  if (ownerJid) {
+    clauses.push(`${tableAlias}.owner_jid = ?`);
+    params.push(ownerJid);
+  }
+
+  if (!clauses.length) return null;
+
+  return {
+    clause: clauses.join(' OR '),
+    params,
+  };
+};
+
+const mapCredentialRow = (row, { includeHash = false } = {}) => {
+  if (!row || typeof row !== 'object') return null;
+
+  const payload = {
+    google_sub: normalizeGoogleSubject(row.google_sub),
+    email: normalizeEmail(row.email),
+    owner_jid: normalizeJid(row.owner_jid),
+    name: normalizeName(row.name),
+    picture:
+      String(row.picture_url || '')
+        .trim()
+        .slice(0, 1024) || null,
+    password_algo:
+      String(row.password_algo || '')
+        .trim()
+        .toLowerCase() || 'argon2id',
+    password_cost: Math.max(0, Number(row.password_cost || 0)),
+    failed_attempts: Math.max(0, Number(row.failed_attempts || 0)),
+    last_failed_at: toIsoOrNull(row.last_failed_at),
+    last_login_at: toIsoOrNull(row.last_login_at),
+    password_changed_at: toIsoOrNull(row.password_changed_at),
+    revoked_at: toIsoOrNull(row.revoked_at),
+    created_at: toIsoOrNull(row.created_at),
+    updated_at: toIsoOrNull(row.updated_at),
+    has_password: Boolean(row.password_hash),
+    active: !row.revoked_at,
+  };
+
+  if (includeHash) {
+    payload.password_hash = String(row.password_hash || '');
+  }
+
+  return payload;
+};
+
+export const createUserPasswordAuthService = ({ executeQuery, tables = {}, logger = null, policy = {} } = {}) => {
+  if (typeof executeQuery !== 'function') {
+    throw new TypeError('createUserPasswordAuthService requer executeQuery valido.');
+  }
+
+  const resolvedPolicy = resolveUserPasswordPolicy(policy);
+
+  const GOOGLE_USER_TABLE = String(tables.STICKER_WEB_GOOGLE_USER || 'web_google_user').trim() || 'web_google_user';
+  const USER_PASSWORD_TABLE = String(tables.STICKER_WEB_USER_PASSWORD || 'web_user_password').trim() || 'web_user_password';
+  const maxFailedAttempts = clampInt(process.env.WEB_USER_PASSWORD_MAX_FAILED_ATTEMPTS, 8, 3, 100);
+  const lockoutSeconds = clampInt(process.env.WEB_USER_PASSWORD_LOCKOUT_SECONDS, 900, 30, 86_400);
+
+  const resolveCredentialLockState = (credential) => {
+    const failures = Math.max(0, Number(credential?.failed_attempts || 0));
+    if (failures < maxFailedAttempts) {
+      return { locked: false, retryAfterSeconds: 0 };
+    }
+
+    const lastFailedAtMs = Date.parse(String(credential?.last_failed_at || ''));
+    if (!Number.isFinite(lastFailedAtMs) || lastFailedAtMs <= 0) {
+      return { locked: false, retryAfterSeconds: 0 };
+    }
+
+    const elapsedSeconds = Math.max(0, Math.floor((Date.now() - lastFailedAtMs) / 1000));
+    const retryAfterSeconds = Math.max(0, lockoutSeconds - elapsedSeconds);
+    if (retryAfterSeconds <= 0) {
+      return { locked: false, retryAfterSeconds: 0 };
+    }
+
+    return { locked: true, retryAfterSeconds };
+  };
+
+  const findKnownGoogleUserByIdentity = async (identity = {}, connection = null) => {
+    const normalizedIdentity = normalizeIdentity(identity);
+    if (!normalizedIdentity.hasIdentity) return null;
+
+    const filter = buildIdentityFilterClause(normalizedIdentity, 'u');
+    if (!filter) return null;
+
+    const rows = await executeQuery(
+      `SELECT u.google_sub, u.email, u.owner_jid, u.name, u.picture_url, u.last_login_at, u.last_seen_at, u.created_at, u.updated_at
+         FROM ${GOOGLE_USER_TABLE} u
+        WHERE ${filter.clause}
+        ORDER BY COALESCE(u.last_seen_at, u.last_login_at, u.updated_at, u.created_at) DESC
+        LIMIT 1`,
+      filter.params,
+      connection,
+    );
+
+    const row = Array.isArray(rows) ? rows[0] : null;
+    if (!row) return null;
+
+    return {
+      google_sub: normalizeGoogleSubject(row.google_sub),
+      email: normalizeEmail(row.email),
+      owner_jid: normalizeJid(row.owner_jid),
+      name: normalizeName(row.name),
+      picture:
+        String(row.picture_url || '')
+          .trim()
+          .slice(0, 1024) || null,
+      last_login_at: toIsoOrNull(row.last_login_at),
+      last_seen_at: toIsoOrNull(row.last_seen_at),
+      created_at: toIsoOrNull(row.created_at),
+      updated_at: toIsoOrNull(row.updated_at),
+    };
+  };
+
+  const findCredentialByIdentityInternal = async (identity = {}, { includeRevoked = false, includeHash = false } = {}, connection = null) => {
+    const normalizedIdentity = normalizeIdentity(identity);
+    if (!normalizedIdentity.hasIdentity) return null;
+
+    const filter = buildIdentityFilterClause(normalizedIdentity, 'u');
+    if (!filter) return null;
+
+    const revokedClause = includeRevoked ? '' : 'AND p.revoked_at IS NULL';
+
+    const rows = await executeQuery(
+      `SELECT
+         p.google_sub,
+         p.password_hash,
+         p.password_algo,
+         p.password_cost,
+         p.failed_attempts,
+         p.last_failed_at,
+         p.last_login_at,
+         p.password_changed_at,
+         p.revoked_at,
+         p.created_at,
+         p.updated_at,
+         u.email,
+         u.owner_jid,
+         u.name,
+         u.picture_url
+       FROM ${USER_PASSWORD_TABLE} p
+       INNER JOIN ${GOOGLE_USER_TABLE} u ON u.google_sub = p.google_sub
+      WHERE (${filter.clause})
+        ${revokedClause}
+      ORDER BY p.updated_at DESC
+      LIMIT 1`,
+      filter.params,
+      connection,
+    );
+
+    return mapCredentialRow(Array.isArray(rows) ? rows[0] : null, { includeHash });
+  };
+
+  const touchCredentialSuccess = async (googleSub, connection = null) => {
+    const normalizedSub = normalizeGoogleSubject(googleSub);
+    if (!normalizedSub) return 0;
+
+    const result = await executeQuery(
+      `UPDATE ${USER_PASSWORD_TABLE}
+          SET failed_attempts = 0,
+              last_failed_at = NULL,
+              last_login_at = UTC_TIMESTAMP(),
+              updated_at = UTC_TIMESTAMP()
+        WHERE google_sub = ?
+          AND revoked_at IS NULL`,
+      [normalizedSub],
+      connection,
+    );
+
+    return Number(result?.affectedRows || 0);
+  };
+
+  const touchCredentialFailure = async (googleSub, connection = null) => {
+    const normalizedSub = normalizeGoogleSubject(googleSub);
+    if (!normalizedSub) return 0;
+
+    const result = await executeQuery(
+      `UPDATE ${USER_PASSWORD_TABLE}
+          SET failed_attempts = failed_attempts + 1,
+              last_failed_at = UTC_TIMESTAMP(),
+              updated_at = UTC_TIMESTAMP()
+        WHERE google_sub = ?
+          AND revoked_at IS NULL`,
+      [normalizedSub],
+      connection,
+    );
+
+    return Number(result?.affectedRows || 0);
+  };
+
+  const setPasswordForIdentity = async ({ googleSub = '', email = '', ownerJid = '', password = '' } = {}, connection = null) => {
+    const knownUser = await findKnownGoogleUserByIdentity({ googleSub, email, ownerJid }, connection);
+    if (!knownUser?.google_sub) {
+      throw buildHttpError('Usuario web nao encontrado. O usuario precisa autenticar no site antes de cadastrar senha.', {
+        statusCode: 404,
+        code: 'USER_NOT_FOUND',
+      });
+    }
+
+    const hashData = await hashUserPassword(password, resolvedPolicy);
+
+    await executeQuery(
+      `INSERT INTO ${USER_PASSWORD_TABLE}
+        (google_sub, password_hash, password_algo, password_cost, failed_attempts, last_failed_at, last_login_at, password_changed_at, revoked_at)
+       VALUES (?, ?, ?, ?, 0, NULL, NULL, UTC_TIMESTAMP(), NULL)
+       ON DUPLICATE KEY UPDATE
+        password_hash = VALUES(password_hash),
+        password_algo = VALUES(password_algo),
+        password_cost = VALUES(password_cost),
+        failed_attempts = 0,
+        last_failed_at = NULL,
+        password_changed_at = UTC_TIMESTAMP(),
+        revoked_at = NULL,
+        updated_at = UTC_TIMESTAMP()`,
+      [knownUser.google_sub, hashData.hash, hashData.algorithm, hashData.cost],
+      connection,
+    );
+
+    const credential = await findCredentialByIdentityInternal({ googleSub: knownUser.google_sub }, { includeRevoked: true }, connection);
+    if (!credential) {
+      throw buildHttpError('Falha ao salvar credencial de senha do usuario.', {
+        statusCode: 500,
+        code: 'PASSWORD_SAVE_FAILED',
+      });
+    }
+
+    if (logger && typeof logger.info === 'function') {
+      logger.info('Credencial de senha do usuario registrada/atualizada.', {
+        action: 'web_user_password_upsert',
+        google_sub: credential.google_sub,
+      });
+    }
+
+    return credential;
+  };
+
+  const verifyPasswordForIdentity = async ({ googleSub = '', email = '', ownerJid = '', password = '' } = {}, connection = null) => {
+    const rawPassword = typeof password === 'string' ? password : '';
+    if (!rawPassword) {
+      return {
+        authenticated: false,
+        reason: 'PASSWORD_REQUIRED',
+        credential: null,
+      };
+    }
+
+    const credentialWithHash = await findCredentialByIdentityInternal({ googleSub, email, ownerJid }, { includeRevoked: true, includeHash: true }, connection);
+    if (!credentialWithHash?.google_sub) {
+      return {
+        authenticated: false,
+        reason: 'CREDENTIAL_NOT_FOUND',
+        credential: null,
+      };
+    }
+
+    if (credentialWithHash.revoked_at) {
+      return {
+        authenticated: false,
+        reason: 'CREDENTIAL_REVOKED',
+        credential: mapCredentialRow(credentialWithHash),
+      };
+    }
+
+    const lockState = resolveCredentialLockState(credentialWithHash);
+    if (lockState.locked) {
+      return {
+        authenticated: false,
+        reason: 'ACCOUNT_LOCKED',
+        retryAfterSeconds: lockState.retryAfterSeconds,
+        credential: mapCredentialRow(credentialWithHash),
+      };
+    }
+
+    const isValid = await verifyUserPasswordHash(rawPassword, credentialWithHash.password_hash);
+
+    if (isValid) {
+      await touchCredentialSuccess(credentialWithHash.google_sub, connection);
+      const updatedCredential = await findCredentialByIdentityInternal({ googleSub: credentialWithHash.google_sub }, { includeRevoked: true }, connection);
+      return {
+        authenticated: true,
+        reason: null,
+        credential: updatedCredential,
+      };
+    }
+
+    await touchCredentialFailure(credentialWithHash.google_sub, connection);
+    const updatedCredential = await findCredentialByIdentityInternal({ googleSub: credentialWithHash.google_sub }, { includeRevoked: true }, connection);
+    const updatedLockState = resolveCredentialLockState(updatedCredential);
+
+    return {
+      authenticated: false,
+      reason: updatedLockState.locked ? 'ACCOUNT_LOCKED' : 'INVALID_PASSWORD',
+      retryAfterSeconds: updatedLockState.retryAfterSeconds,
+      credential: updatedCredential,
+    };
+  };
+
+  const revokePasswordForIdentity = async ({ googleSub = '', email = '', ownerJid = '' } = {}, connection = null) => {
+    const existing = await findCredentialByIdentityInternal({ googleSub, email, ownerJid }, { includeRevoked: true }, connection);
+    if (!existing?.google_sub) return null;
+
+    await executeQuery(
+      `UPDATE ${USER_PASSWORD_TABLE}
+          SET revoked_at = COALESCE(revoked_at, UTC_TIMESTAMP()),
+              updated_at = UTC_TIMESTAMP()
+        WHERE google_sub = ?`,
+      [existing.google_sub],
+      connection,
+    );
+
+    return findCredentialByIdentityInternal({ googleSub: existing.google_sub }, { includeRevoked: true }, connection);
+  };
+
+  const clearFailuresForIdentity = async ({ googleSub = '', email = '', ownerJid = '' } = {}, connection = null) => {
+    const existing = await findCredentialByIdentityInternal({ googleSub, email, ownerJid }, { includeRevoked: true }, connection);
+    if (!existing?.google_sub) return null;
+
+    await executeQuery(
+      `UPDATE ${USER_PASSWORD_TABLE}
+          SET failed_attempts = 0,
+              last_failed_at = NULL,
+              updated_at = UTC_TIMESTAMP()
+        WHERE google_sub = ?`,
+      [existing.google_sub],
+      connection,
+    );
+
+    return findCredentialByIdentityInternal({ googleSub: existing.google_sub }, { includeRevoked: true }, connection);
+  };
+
+  return {
+    policy: {
+      ...resolvedPolicy,
+      maxFailedAttempts,
+      lockoutSeconds,
+    },
+    getPolicy: () => ({
+      ...resolvedPolicy,
+      maxFailedAttempts,
+      lockoutSeconds,
+    }),
+    validatePassword: (password) => validateUserPassword(password, resolvedPolicy),
+    findKnownGoogleUserByIdentity,
+    findCredentialByIdentity: (identity = {}, options = {}, connection = null) => findCredentialByIdentityInternal(identity, options, connection),
+    setPasswordForIdentity,
+    verifyPasswordForIdentity,
+    revokePasswordForIdentity,
+    clearFailuresForIdentity,
+  };
+};

package/server/auth/userPassword/userPasswordCrypto.js

@@ -0,0 +1,199 @@
+import argon2 from 'argon2';
+
+const clampInt = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const parseEnvBool = (value, fallback = false) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const DEFAULT_ARGON2_TIME_COST = 3;
+const MIN_ARGON2_TIME_COST = 2;
+const MAX_ARGON2_TIME_COST = 10;
+
+const DEFAULT_ARGON2_MEMORY_KB = 19_456;
+const MIN_ARGON2_MEMORY_KB = 4_096;
+const MAX_ARGON2_MEMORY_KB = 262_144;
+
+const DEFAULT_ARGON2_PARALLELISM = 1;
+const MIN_ARGON2_PARALLELISM = 1;
+const MAX_ARGON2_PARALLELISM = 8;
+
+const DEFAULT_ARGON2_HASH_LENGTH = 32;
+const MIN_ARGON2_HASH_LENGTH = 16;
+const MAX_ARGON2_HASH_LENGTH = 64;
+
+const DEFAULT_MIN_LENGTH = 12;
+const DEFAULT_MAX_LENGTH = 72;
+const MIN_ALLOWED_LENGTH = 10;
+const MAX_ALLOWED_LENGTH = 72;
+
+const ARGON2_PREFIX = '$argon2id$';
+const MIN_PEPPER_SECRET_LENGTH = 16;
+
+const DEFAULT_POLICY_INPUT = {
+  argon2TimeCost: clampInt(process.env.WEB_USER_PASSWORD_ARGON2_TIME_COST, DEFAULT_ARGON2_TIME_COST, MIN_ARGON2_TIME_COST, MAX_ARGON2_TIME_COST),
+  argon2MemoryKb: clampInt(process.env.WEB_USER_PASSWORD_ARGON2_MEMORY_KB, DEFAULT_ARGON2_MEMORY_KB, MIN_ARGON2_MEMORY_KB, MAX_ARGON2_MEMORY_KB),
+  argon2Parallelism: clampInt(process.env.WEB_USER_PASSWORD_ARGON2_PARALLELISM, DEFAULT_ARGON2_PARALLELISM, MIN_ARGON2_PARALLELISM, MAX_ARGON2_PARALLELISM),
+  argon2HashLength: clampInt(process.env.WEB_USER_PASSWORD_ARGON2_HASH_LENGTH, DEFAULT_ARGON2_HASH_LENGTH, MIN_ARGON2_HASH_LENGTH, MAX_ARGON2_HASH_LENGTH),
+  minLength: clampInt(process.env.WEB_USER_PASSWORD_MIN_LENGTH, DEFAULT_MIN_LENGTH, MIN_ALLOWED_LENGTH, MAX_ALLOWED_LENGTH),
+  maxLength: clampInt(process.env.WEB_USER_PASSWORD_MAX_LENGTH, DEFAULT_MAX_LENGTH, MIN_ALLOWED_LENGTH, MAX_ALLOWED_LENGTH),
+  requireLetter: parseEnvBool(process.env.WEB_USER_PASSWORD_REQUIRE_LETTER, true),
+  requireNumber: parseEnvBool(process.env.WEB_USER_PASSWORD_REQUIRE_NUMBER, true),
+};
+
+const normalizePolicyLength = (minLength, maxLength) => {
+  const safeMin = clampInt(minLength, DEFAULT_MIN_LENGTH, MIN_ALLOWED_LENGTH, MAX_ALLOWED_LENGTH);
+  const safeMax = clampInt(maxLength, DEFAULT_MAX_LENGTH, MIN_ALLOWED_LENGTH, MAX_ALLOWED_LENGTH);
+
+  if (safeMin <= safeMax) {
+    return {
+      minLength: safeMin,
+      maxLength: safeMax,
+    };
+  }
+
+  return {
+    minLength: safeMax,
+    maxLength: safeMax,
+  };
+};
+
+export const resolveUserPasswordPolicy = (overrides = {}) => {
+  const merged = {
+    ...DEFAULT_POLICY_INPUT,
+    ...(overrides && typeof overrides === 'object' ? overrides : {}),
+  };
+
+  const lengthPolicy = normalizePolicyLength(merged.minLength, merged.maxLength);
+
+  return {
+    argon2TimeCost: clampInt(merged.argon2TimeCost ?? merged.bcryptRounds, DEFAULT_POLICY_INPUT.argon2TimeCost, MIN_ARGON2_TIME_COST, MAX_ARGON2_TIME_COST),
+    argon2MemoryKb: clampInt(merged.argon2MemoryKb, DEFAULT_POLICY_INPUT.argon2MemoryKb, MIN_ARGON2_MEMORY_KB, MAX_ARGON2_MEMORY_KB),
+    argon2Parallelism: clampInt(merged.argon2Parallelism, DEFAULT_POLICY_INPUT.argon2Parallelism, MIN_ARGON2_PARALLELISM, MAX_ARGON2_PARALLELISM),
+    argon2HashLength: clampInt(merged.argon2HashLength, DEFAULT_POLICY_INPUT.argon2HashLength, MIN_ARGON2_HASH_LENGTH, MAX_ARGON2_HASH_LENGTH),
+    // Compatibilidade temporaria para consumidores legados.
+    bcryptRounds: clampInt(merged.argon2TimeCost ?? merged.bcryptRounds, DEFAULT_POLICY_INPUT.argon2TimeCost, MIN_ARGON2_TIME_COST, MAX_ARGON2_TIME_COST),
+    minLength: lengthPolicy.minLength,
+    maxLength: lengthPolicy.maxLength,
+    requireLetter: Boolean(merged.requireLetter),
+    requireNumber: Boolean(merged.requireNumber),
+  };
+};
+
+export const DEFAULT_USER_PASSWORD_POLICY = resolveUserPasswordPolicy();
+
+const buildValidationError = (errors) => {
+  const firstMessage = errors[0]?.message || 'Senha invalida.';
+  const error = new Error(firstMessage);
+  error.statusCode = 400;
+  error.code = 'INVALID_PASSWORD';
+  error.details = errors;
+  return error;
+};
+
+export const validateUserPassword = (password, policyOverrides = {}) => {
+  const policy = resolveUserPasswordPolicy(policyOverrides);
+  const rawPassword = typeof password === 'string' ? password : '';
+  const errors = [];
+
+  if (!rawPassword) {
+    errors.push({ code: 'PASSWORD_REQUIRED', message: 'Senha obrigatoria.' });
+  }
+
+  if (rawPassword && rawPassword.trim().length === 0) {
+    errors.push({
+      code: 'PASSWORD_WHITESPACE_ONLY',
+      message: 'Senha nao pode conter apenas espacos.',
+    });
+  }
+
+  if (rawPassword.length > 0 && rawPassword.length < policy.minLength) {
+    errors.push({
+      code: 'PASSWORD_TOO_SHORT',
+      message: `Senha deve ter no minimo ${policy.minLength} caracteres.`,
+    });
+  }
+
+  if (rawPassword.length > policy.maxLength) {
+    errors.push({
+      code: 'PASSWORD_TOO_LONG',
+      message: `Senha deve ter no maximo ${policy.maxLength} caracteres.`,
+    });
+  }
+
+  if (policy.requireLetter && rawPassword && !/[a-z]/i.test(rawPassword)) {
+    errors.push({
+      code: 'PASSWORD_LETTER_REQUIRED',
+      message: 'Senha deve conter pelo menos uma letra.',
+    });
+  }
+
+  if (policy.requireNumber && rawPassword && !/\d/.test(rawPassword)) {
+    errors.push({
+      code: 'PASSWORD_NUMBER_REQUIRED',
+      message: 'Senha deve conter pelo menos um numero.',
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    policy,
+  };
+};
+
+const resolvePepperSecret = (overrideValue = '') => {
+  const secret = String(overrideValue || process.env.WEB_USER_PASSWORD_PEPPER_SECRET || '').trim();
+  if (secret.length >= MIN_PEPPER_SECRET_LENGTH) return secret;
+
+  const error = new Error(`WEB_USER_PASSWORD_PEPPER_SECRET deve ter no minimo ${MIN_PEPPER_SECRET_LENGTH} caracteres.`);
+  error.statusCode = 500;
+  error.code = 'PASSWORD_PEPPER_NOT_CONFIGURED';
+  throw error;
+};
+
+const buildPepperedPassword = (password, pepperSecret) => `${String(password || '')}${pepperSecret}`;
+
+export const hashUserPassword = async (password, policyOverrides = {}, options = {}) => {
+  const validation = validateUserPassword(password, policyOverrides);
+  if (!validation.valid) {
+    throw buildValidationError(validation.errors);
+  }
+
+  const pepperSecret = resolvePepperSecret(options?.pepperSecret);
+  const hash = await argon2.hash(buildPepperedPassword(password, pepperSecret), {
+    type: argon2.argon2id,
+    timeCost: validation.policy.argon2TimeCost,
+    memoryCost: validation.policy.argon2MemoryKb,
+    parallelism: validation.policy.argon2Parallelism,
+    hashLength: validation.policy.argon2HashLength,
+  });
+
+  return {
+    hash,
+    algorithm: 'argon2id',
+    cost: validation.policy.argon2TimeCost,
+    policy: validation.policy,
+  };
+};
+
+export const verifyUserPasswordHash = async (password, passwordHash, options = {}) => {
+  const rawHash = String(passwordHash || '').trim();
+  if (!rawHash) return false;
+  if (!rawHash.startsWith(ARGON2_PREFIX)) return false;
+
+  try {
+    const pepperSecret = resolvePepperSecret(options?.pepperSecret);
+    return await argon2.verify(rawHash, buildPepperedPassword(password, pepperSecret));
+  } catch {
+    return false;
+  }
+};

package/server/auth/userPassword/userPasswordCrypto.test.js

@@ -0,0 +1,76 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { hashUserPassword, resolveUserPasswordPolicy, validateUserPassword, verifyUserPasswordHash } from './userPasswordCrypto.js';
+
+const TEST_PEPPER_SECRET = 'pepper-secreto-de-teste-argon2';
+process.env.WEB_USER_PASSWORD_PEPPER_SECRET = TEST_PEPPER_SECRET;
+
+test('resolveUserPasswordPolicy normaliza limites de Argon2 e tamanho', () => {
+  const policy = resolveUserPasswordPolicy({
+    argon2TimeCost: 99,
+    argon2MemoryKb: 999_999,
+    argon2Parallelism: 99,
+    argon2HashLength: 999,
+    minLength: 120,
+    maxLength: 4,
+  });
+
+  assert.equal(policy.argon2TimeCost, 10);
+  assert.equal(policy.argon2MemoryKb, 262_144);
+  assert.equal(policy.argon2Parallelism, 8);
+  assert.equal(policy.argon2HashLength, 64);
+  assert.equal(policy.minLength, 10);
+  assert.equal(policy.maxLength, 10);
+});
+
+test('validateUserPassword reprova senha curta', () => {
+  const result = validateUserPassword('abc', {
+    minLength: 10,
+    maxLength: 72,
+  });
+
+  assert.equal(result.valid, false);
+  assert.equal(
+    result.errors.some((item) => item.code === 'PASSWORD_TOO_SHORT'),
+    true,
+  );
+});
+
+test('hashUserPassword + verifyUserPasswordHash validam senha correta', async () => {
+  const password = 'SenhaInterna123';
+  const hashed = await hashUserPassword(password, {
+    argon2TimeCost: 2,
+    argon2MemoryKb: 4_096,
+    argon2Parallelism: 1,
+    argon2HashLength: 24,
+    minLength: 10,
+    maxLength: 72,
+  });
+
+  assert.equal(typeof hashed.hash, 'string');
+  assert.equal(hashed.hash.startsWith('$argon2id$'), true);
+  assert.equal(hashed.algorithm, 'argon2id');
+
+  const valid = await verifyUserPasswordHash(password, hashed.hash);
+  assert.equal(valid, true);
+});
+
+test('verifyUserPasswordHash retorna false para senha incorreta', async () => {
+  const hashed = await hashUserPassword('SenhaCorreta123', {
+    argon2TimeCost: 2,
+    argon2MemoryKb: 4_096,
+    argon2Parallelism: 1,
+    argon2HashLength: 24,
+    minLength: 10,
+    maxLength: 72,
+  });
+
+  const valid = await verifyUserPasswordHash('SenhaErrada', hashed.hash);
+  assert.equal(valid, false);
+});
+
+test('verifyUserPasswordHash retorna false para hash invalido', async () => {
+  const valid = await verifyUserPasswordHash('qualquer', 'nao-e-hash-argon2');
+  assert.equal(valid, false);
+});