disarm 0.0.0 → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Quinn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,87 @@
-# disarm (placeholder)
+# disarm (Node.js)
 
-Name reserved for a forthcoming library: secure text transliteration, Unicode
-normalization, and safe key/slug generation (formerly `translit`).
+Unicode confusable/text-security building blocks for Node.js — TR39 *visual*
+homoglyph folding, deobfuscation (bidi / zalgo / zero-width / invisible / emoji),
+and standards-based *phonetic* transliteration. Powered by a **pure-Rust core**
+([`disarm`](https://crates.io/crates/disarm)) via [napi-rs](https://napi.rs); the
+prebuilt native addons install with no Rust toolchain.
 
-This `0.0.0` release is an intentional placeholder and has no functional API.
+```sh
+npm install disarm
+```
 
-Project: https://github.com/raeq/disarm
+Ships TypeScript types (`.d.ts`) — no `@types/disarm` needed. Requires Node 14+.
+
+## Quick start
+
+```ts
+import {
+  normalizeConfusables,
+  transliterate,
+  slugify,
+  isSuspiciousHostname,
+} from 'disarm'
+
+// Visual (TR39) confusable folding — homoglyph defence
+normalizeConfusables('раypal') // → 'paypal'  (Cyrillic а/р folded to Latin)
+
+// Phonetic romanization — readable ASCII, NOT a security control.
+// A language profile sharpens the output: the uk profile gives Київ → Kyiv.
+transliterate('Київ', { lang: 'uk' }) // → 'Kyiv'
+slugify('Héllo Wörld') // → 'hello-world'
+
+// Hostname / IDN spoof check (a false result is not a safety guarantee)
+isSuspiciousHostname('pаypal.com') // → true  (Cyrillic 'а')
+```
+
+The two operations people most often confuse are *visual* confusable folding
+(homoglyph defence) and *phonetic* transliteration (romanization) — see
+[Which function do I want?](https://docs.disarm.dev/concepts/which-function/).
+
+## Idioms
+
+- **Options objects with defaults** — `transliterate(text, { scheme, lang })`,
+  `slugify(text, { separator, maxLength, … })`, `normalize(text, { form })`.
+- **String-union tokens** — `scheme: 'default' | 'strict_iso9' | 'gost7034'`,
+  `form: 'NFC' | 'NFD' | 'NFKC' | 'NFKD'`, `platform: 'universal' | 'windows' | 'posix'`,
+  fully typed in your editor.
+- **A native error type** — bad input (an unknown scheme/target/form/platform)
+  throws `DisarmInvalidArgument`, a subclass of `DisarmError`:
+
+  ```ts
+  import { transliterate, DisarmError } from 'disarm'
+
+  try {
+    transliterate('x', { scheme: 'klingon' })
+  } catch (e) {
+    if (e instanceof DisarmError) console.warn(e.message)
+  }
+  ```
+
+## What's here
+
+Transliteration (`transliterate`, `reverseTransliterate`, `findUntranslatable`),
+confusables (`normalizeConfusables`, `isConfusable`), slugs (`slugify`),
+normalization (`normalize`, `isNormalized`), text cleaning (`collapseWhitespace`,
+`stripControlChars`, `stripZeroWidthChars`, `stripBidi`, `stripZalgo`, `isZalgo`),
+deobfuscation/security presets (`stripObfuscation`, `canonicalize`,
+`sanitizeFilename`), grapheme clusters (`graphemeLen`, `graphemeSplit`,
+`graphemeTruncate`, `graphemeWidth`, `terminalWidth`), and script analysis
+(`detectScripts`, `isMixedScript`, `isSuspiciousHostname`, `inspectAutoLang`).
+Every export is fully typed.
+
+## Security posture
+
+disarm normalizes **input**; it is a defense-in-depth layer, **not** an output
+sanitizer. It performs no escaping and is not an XSS/SQL/HTML defense — encode at
+the output sink. Read the
+[Threat Model](https://github.com/raeq/disarm/blob/main/THREAT_MODEL.md) before
+relying on it in a security context.
+
+## Links
+
+- **Docs:** <https://docs.disarm.dev>
+- **Core (Rust):** <https://crates.io/crates/disarm>
+- **Source / issues:** <https://github.com/raeq/disarm>
+
+MIT licensed.

package/binding.d.ts

@@ -0,0 +1,283 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * A reusable, opaque lexicon handle (HAI-SDLC 6.1).
+ *
+ * `hasAnomalies` / `inspectAnomalies` rebuild a `HashSet<String>` from the
+ * caller's word array on every call. A caller hitting these in a loop with a
+ * large lexicon pays that rebuild each time. `Lexicon` builds the internal set
+ * once in its constructor and is then reused across calls.
+ */
+export declare class Lexicon {
+  /**
+   * Build a reusable lexicon from a word list, folding it into the internal
+   * set once.
+   */
+  constructor(words: Array<string>)
+}
+
+/**
+ * A reusable, opaque named-policy-profile pipeline handle (#404).
+ *
+ * `getPipeline` validates and compiles a profile's steps once; the resulting
+ * handle is then applied to any number of inputs via `process`. Like the
+ * `Lexicon` handle, the build cost is paid a single time and reused across
+ * calls, rather than re-resolved per call.
+ */
+export declare class Pipeline {
+  /** Run the named pipeline over `text`, returning the cleaned string. */
+  process(text: string): string
+}
+
+/** Structured anomaly report. */
+export interface AnomalyReport {
+  /** Whether any token tripped (the same value `hasAnomalies` returns). */
+  anomalous: boolean
+  /** The anomaly kinds that fired, in first-appearance order. */
+  kinds: Array<string>
+  /** Every finding, with span and detail. */
+  findings: Array<Finding>
+  /** The first finding's reason, if any. */
+  reason?: string
+}
+
+/** How `lang: "auto"` detection resolves `text`. */
+export interface AutoLangInspection {
+  /** The primary non-Latin script detected, if any (e.g. `"Cyrillic"`). */
+  script?: string
+  /** The language auto-detection chose, if any (e.g. `"ru"`). */
+  chosenLang?: string
+  /** Why that choice was made. */
+  reason: string
+  /** The discriminator characters that drove the choice, if any. */
+  discriminatorsHit: Array<string>
+}
+
+export declare function canonicalize(text: string): string
+
+/**
+ * Library catalog deduplication key (like `searchKey` plus confusable folding).
+ * `lang` selects the transliteration table; `strict_iso9` picks the ISO 9:1995
+ * Cyrillic scheme.
+ */
+export declare function catalogKey(text: string, lang: string | undefined | null, strictIso9: boolean): string
+
+export declare function collapseWhitespace(text: string): string
+
+/** Replace emoji with their plain names; `strip_modifiers` drops skin-tone marks. */
+export declare function demojize(text: string, stripModifiers: boolean): string
+
+/**
+ * The Unicode scripts present, in first-appearance order (Common/Inherited
+ * excluded), as stable UCD identifiers.
+ */
+export declare function detectScripts(text: string): Array<string>
+
+/** One reason a token is anomalous (a single finding). */
+export interface Finding {
+  /** Which branch fired: `"invisible"` | `"bidi"` | `"zalgo"` | `"mixed_script"` | `"bidi_mixed"` | `"leet"` | `"segmentation"`. */
+  kind: string
+  /** The offending whitespace token, as it appeared. */
+  token: string
+  /** Byte offset of the token start in the input. */
+  start: number
+  /** Byte offset of the token end in the input. */
+  end: number
+  /** Evidence: the codepoint, the scripts, or the decoded word. */
+  detail: string
+  /** A plain-language sentence describing the finding. */
+  reason: string
+}
+
+/** Characters with no romanization, as `{ char, offset }` (byte offset), in order. */
+export declare function findUntranslatable(text: string, scheme: string, lang?: string | undefined | null): Array<Untranslatable>
+
+export declare function foldCase(text: string): string
+
+/**
+ * `getPipeline(profile)` — build a reusable `Pipeline` handle for a named
+ * policy profile. An unknown profile raises a `DisarmInvalidArgument`-tagged
+ * error naming the available profiles.
+ */
+export declare function getPipeline(profile: string): Pipeline
+
+export declare function graphemeLen(text: string): number
+
+export declare function graphemeSplit(text: string): Array<string>
+
+export declare function graphemeTruncate(text: string, maxGraphemes: number): string
+
+export declare function graphemeWidth(cluster: string, ambiguousWide: boolean): number
+
+/**
+ * `hasAnomalies(text, lexicon)` — `lexicon` is either an array of common words
+ * or a prebuilt `Lexicon` handle (no per-call rebuild).
+ */
+export declare function hasAnomalies(text: string, lexicon: Array<string> | Lexicon): boolean
+
+/**
+ * Whether `text` mixes strong left-to-right and strong right-to-left characters
+ * — the precondition for Bidi display-reordering ("BiDi Swap"). Fires on the
+ * real letters (no `U+202x` override); a `false` result is not a safety
+ * guarantee.
+ */
+export declare function hasBidiConflict(text: string): boolean
+
+/**
+ * `inspectAnomalies(text, lexicon)` — full analysis with per-token findings.
+ * `lexicon` is either an array of common words or a prebuilt `Lexicon` handle.
+ */
+export declare function inspectAnomalies(text: string, lexicon: Array<string> | Lexicon): AnomalyReport
+
+/** Explain how auto-language detection resolves `text`. */
+export declare function inspectAutoLang(text: string): AutoLangInspection
+
+/** Whether `text` contains a character confusable with `target`. */
+export declare function isConfusable(text: string, target: string): boolean
+
+/** Whether `text` mixes characters from more than one script. */
+export declare function isMixedScript(text: string): boolean
+
+/** Whether `text` is already in normalization `form`. */
+export declare function isNormalized(text: string, form: string): boolean
+
+/**
+ * Whether the hostname looks like a mixed-script / confusable / bidi-reorder
+ * IDN spoof. Flags a single mixed-script label, a Latin confusable, or a
+ * bidi-direction conflict (`hasBidiConflict`, the "BiDi Swap" precondition,
+ * #412). A `false` asserts nothing was *found*, not that the host is safe.
+ */
+export declare function isSuspiciousHostname(host: string): boolean
+
+export declare function isZalgo(text: string, threshold: number): boolean
+
+/**
+ * Look up static facts about a language `code`. An unknown code raises a
+ * `DisarmInvalidArgument`-tagged error.
+ */
+export declare function langInfo(code: string): LangMeta
+
+/** Static facts about a language profile (the `lang` codes accepted across the API). */
+export interface LangMeta {
+  /** The language's English name (e.g. `"German"`). */
+  name: string
+  /** The primary script it is written in (e.g. `"Latin"`). */
+  script: string
+  /** The region/locale it is associated with. */
+  region: string
+  /** Context-aware transliteration support: `"none"`, `"partial"`, or `"full"`. */
+  context: string
+}
+
+/** Every language code that has a context-aware transliteration profile. */
+export declare function listContextLangs(): Array<string>
+
+/** Every Unicode script name known to the transliteration tables. */
+export declare function listScripts(): Array<string>
+
+/** Apply a normalization form: `"NFC"` | `"NFD"` | `"NFKC"` | `"NFKD"`. */
+export declare function normalize(text: string, form: string): string
+
+/** Fold cross-script confusables toward `target` (`"latin"` | `"cyrillic"`). */
+export declare function normalizeConfusables(text: string, target: string): string
+
+/** Reverse-transliterate Latin → native script. `lang` is `"el"` | `"ru"` | `"uk"`. */
+export declare function reverseTransliterate(text: string, lang: string): string
+
+/**
+ * Turn arbitrary text into a safe filename. `platform` is `"universal"` |
+ * `"windows"` | `"posix"`.
+ */
+export declare function sanitizeFilename(text: string, separator: string, maxLength: number, platform: string, lang: string | undefined | null, preserveExtension: boolean): string
+
+/**
+ * Look up static facts about a script by `name`. An unknown name raises a
+ * `DisarmInvalidArgument`-tagged error.
+ */
+export declare function scriptInfo(name: string): ScriptMeta
+
+/** Static facts about a Unicode script known to the transliteration tables. */
+export interface ScriptMeta {
+  /** The script's name (e.g. `"Coptic"`). */
+  name: string
+  /** The default language code for the script, if any (e.g. `"cop"`). */
+  defaultLang?: string
+  /** A short example string in the script. */
+  example: string
+  /** Whether transliteration of this script is context-aware. */
+  contextAware: boolean
+}
+
+/**
+ * Case/accent/script-insensitive search lookup key. `lang` selects the
+ * transliteration table (omit for none).
+ */
+export declare function searchKey(text: string, lang?: string | undefined | null): string
+
+/** Generate a URL-safe slug. */
+export declare function slugify(text: string, opts: SlugOptions): string
+
+/** The full slug option surface (the TS layer fills defaults before calling). */
+export interface SlugOptions {
+  separator: string
+  lowercase: boolean
+  maxLength: number
+  wordBoundary: boolean
+  saveOrder: boolean
+  stopwords: Array<string>
+  allowUnicode: boolean
+  lang?: string
+  entities: boolean
+  decimal: boolean
+  hexadecimal: boolean
+  safeChars: string
+}
+
+/**
+ * Collation sort key (like `searchKey` but preserves base accented characters
+ * for correct ordering). `lang` selects the transliteration table.
+ */
+export declare function sortKey(text: string, lang?: string | undefined | null): string
+
+export declare function stripAccents(text: string): string
+
+export declare function stripBidi(text: string): string
+
+export declare function stripControlChars(text: string): string
+
+/** Strip every Unicode noncharacter (#413). */
+export declare function stripNoncharacters(text: string): string
+
+export declare function stripObfuscation(text: string): string
+
+/** Strip every Private Use Area code point (#413). */
+export declare function stripPua(text: string): string
+
+/** Strip the Unicode Tags block (U+E0000–U+E007F), preserving valid emoji flags (#413). */
+export declare function stripTags(text: string): string
+
+/** Strip every variation selector (VS1–VS256) (#413). */
+export declare function stripVariationSelectors(text: string): string
+
+export declare function stripZalgo(text: string, maxMarks: number): string
+
+export declare function stripZeroWidthChars(text: string): string
+
+export declare function terminalWidth(text: string, ambiguousWide: boolean): number
+
+/** Unicode → ASCII with the default scheme (the borrow-on-no-op fast path). */
+export declare function transliterate(text: string): string
+
+/**
+ * Transliterate with a scheme (`"default"` | `"strict_iso9"` | `"gost7034"`)
+ * and/or a language profile (`lang`), via the core's builder.
+ */
+export declare function transliterateOpts(text: string, scheme: string, lang?: string | undefined | null): string
+
+/** A character with no transliteration, located in the input. */
+export interface Untranslatable {
+  /** The untranslatable character. */
+  char: string
+  /** Its byte offset in the input string. */
+  offset: number
+}