Registry / auth-security / unicode-confusables

unicode-confusables

library0.1.1jsnpmunverified

The `unicode-confusables` utility provides functions to detect and resolve visually confusing Unicode characters in strings, adhering to the security guidelines outlined in Unicode Technical Standard #39 (UTS39). It leverages the `confusables.txt` data file to identify characters that can be easily mistaken for others, including homoglyphs and zero-width characters. Currently at version 0.1.1, the library's release cadence is tied to updates in the UTS39 standard and `confusables.txt` data. Its primary differentiators include direct adherence to the official Unicode standard, the ability to not only detect but also rectify confused characters, and support for a wide range of scripts, including non-Latin languages. It also provides a mechanism to update its underlying data set, making it crucial for applications requiring robust input validation and security against 'homograph attacks' or similar visual spoofing.

auth-security serialization

npm install unicode-confusables

package ↗

INSTALL

IMPORT

SIG · UNICODE-CONFUSABLE

unicode-confusables

auth-securityjavascriptv0.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

isConfusing

✓ import { isConfusing } from 'unicode-confusables';

✗ const isConfusing = require('unicode-confusables').isConfusing;

While CommonJS `require` is supported, ESM `import` is preferred for modern applications. For CJS, use object destructuring as shown in `wrong` example.

confusables

✓ import { confusables } from 'unicode-confusables';

✗ import confusables from 'unicode-confusables';

This is a named export, not a default export. Incorrectly importing it as a default will result in a TypeError.

rectifyConfusion

✓ import { rectifyConfusion } from 'unicode-confusables';

✗ const { rectifyConfusion } = require('unicode-confusables');

The README shows CommonJS `require` usage. For modern TypeScript/ESM projects, the `import` syntax is standard. The library ships with TypeScript types.

Demonstrates how to check if a string contains confusing Unicode characters, identify the specific confusables, and rectify them. It also shows detection of zero-width characters and homoglyphs.

import { isConfusing, confusables, rectifyConfusion } from 'unicode-confusables'; async function demonstrateConfusables() { const confusingString = 'fоо'; // 'o' here is a Cyrillic 'о' (U+043E) const regularString = 'foo'; console.log(`Is '${confusingString}' confusing? ${isConfusing(confusingString)}`); console.log(`Is '${regularString}' confusing? ${isConfusing(regularString)}`); console.log(`Confusables for '${confusingString}':`, confusables(confusingString)); console.log(`Rectified '${confusingString}': '${rectifyConfusion(confusingString)}'`); const zeroWidthString = 'vitalik\u200b'; // vitalik with a zero-width space (U+200B) console.log(`Is '${zeroWidthString}' confusing (with zero-width char)? ${isConfusing(zeroWidthString)}`); console.log(`Confusables for '${zeroWidthString}':`, confusables(zeroWidthString)); const mixedCaseHomoglyph = 'mI01'; // common homoglyphs for m, I, 0, 1 console.log(`Confusables for '${mixedCaseHomoglyph}':`, confusables(mixedCaseHomoglyph)); } demonstrateConfusables();

Debug

Known issues

breakingAs a 0.x.x version, the API is not yet stable and breaking changes may be introduced in minor or patch versions without a major version increment. It is advisable to pin exact versions or frequently review release notes.

fix

Pin the exact version in `package.json` (e.g., `"unicode-confusables": "0.1.1"`) and review updates manually.

affects: >=0.0.0

gotchaThe underlying `confusables.txt` data, sourced from unicode.org, can be updated. If your application relies on the latest data for security, you must periodically run `npm run update` to fetch and parse a fresh copy.

fix

Integrate `npm run update` into your CI/CD pipeline or a regular maintenance script to ensure the data is current.

affects: >=0.0.0

gotchaThis library's definition of 'confusing' is strictly based on Unicode UTS39. It does not cover all possible visual spoofing methods (e.g., domain squatting, visual similarities not listed in UTS39, or culturally specific visual attacks).

fix

Supplement this library with other security measures appropriate for your application's threat model, and educate users about potential risks beyond UTS39.

affects: >=0.0.0

gotchaProcessing very long strings or making frequent calls to `confusables` or `isConfusing` in a performance-critical loop can be computationally intensive, as it involves character-by-character analysis and lookups.

fix

For performance-sensitive applications, consider caching results for common strings or rate-limiting checks. Profile your application to identify bottlenecks.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: (0, unicode_confusables_1.isConfusing) is not a function

This typically occurs when trying to use named exports with a default import syntax in an ESM environment after TypeScript transpilation.

fix

Ensure you are using named imports: `import { isConfusing } from 'unicode-confusables';`

TypeError: isConfusing is not a function

This happens when attempting to call `isConfusing` on the entire module object, rather than destructuring the named export, particularly in CommonJS.

fix

Use object destructuring for CommonJS `require`: `const { isConfusing } = require('unicode-confusables');`

Module not found: Error: Can't resolve 'unicode-confusables'

The package has not been installed, or there's a typo in the import path.

fix

Run `npm install unicode-confusables` or `yarn add unicode-confusables` to install the package. Verify the import path is exactly `'unicode-confusables'`.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/unicode-confusables ↗