@fazelstudio/username-intelligence

Advanced username analysis library with security scoring, Unicode script detection, homoglyph spoofing prevention, and bot detection — zero regex magic.

Features

• 🌍 Unicode Script Detection — identifies scripts from 100+ languages (Latin, Cyrillic, Arabic, Hangul, Devanagari, etc.)
• 🛡️ Spoofing Prevention — detects homoglyph attacks (Cyrillic а vs Latin a) and invisible characters
• 🤖 Bot & Spam Detection — Shannon entropy analysis catches random keystrokes (xcv892nm)
• 🧠 Smart Classification — categorizes as Personal, Gamer, Corporate, Bot, Leet, and more
• 📊 Quality Scoring — 0–100 scores for readability and security risk
• 🔍 Leet Speak Normalization — h4ck3r → hacker, mathematical font stripping
• ⚡ Batch Analysis — analyze hundreds of usernames with built-in LRU cache
• 🪶 Zero Dependencies — lightweight, tree-shakeable ESM + CJS builds

Installation

npm install @fazelstudio/username-intelligence

Usage

Basic Analysis

import { analyzeUsername } from '@fazelstudio/username-intelligence';

const result = analyzeUsername('h4ck3r_man');

console.log(result.isValid);      // true
console.log(result.classification); // "Gamer"
console.log(result.security.risk_level); // "LOW"

Example Output

{
  "username": "h4ck3r_man",
  "score": 85,
  "classification": "Gamer",
  "isValid": true,
  "flags": ["leet_speak"],
  "security": {
    "risk_level": "LOW",
    "is_spoofing": false,
    "has_hidden_chars": false
  },
  "metadata": {
    "script": "Latin",
    "entropy": 2.5
  }
}

Advanced Options

const result = analyzeUsername('admin_support', {
  strict: true,
  blockProfanity: true,
  reservedWords: ['admin', 'support', 'mod'],
  checkVisual: true,
});

Batch Analysis

import { batchAnalyze } from '@fazelstudio/username-intelligence';

const results = batchAnalyze(['john_doe', 'xX_gamer_Xx', 'admin']);

results.forEach(r => {
  console.log(`${r.username}: ${r.analysis.classification.style} (score: ${r.analysis.classification.scores.quality})`);
});

API Reference

Function	Description
analyzeUsername(username, options?)	Analyze a single username
batchAnalyze(usernames, options?)	Analyze multiple usernames
clearCache()	Clear the LRU analysis cache
getCacheStats()	Get cache hit/miss statistics

Options

Option	Type	Default	Description
strict	boolean	false	Enable stricter validation rules
blockProfanity	boolean	false	Reject usernames containing profanity
reservedWords	string[]	[]	Custom blocked words
checkVisual	boolean	true	Check for visual spoofing
enableCache	boolean	true	Enable LRU result caching
enableSecurity	boolean	true	Enable security analysis
enableLinguistic	boolean	true	Enable linguistic analysis
enableVisual	boolean	true	Enable visual analysis

Use Cases

• Registration Security — block spoofed usernames during sign-up
• Spam Prevention — detect bot-generated random usernames
• Brand Protection — catch impersonation attempts (e.g. раураl with Cyrillic chars)
• UX Gamification — score username quality during onboarding
• Moderation — filter profanity and reserved words

Development

npm install
npm run build
node test-optimization.js
npm run format

License

MIT — © 2026 Fazel

---

username-intelligence — Know who's behind the name.