@ipfy/homoglyph 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IPfy
+
+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/NOTICE

@@ -0,0 +1,45 @@
+This package includes derived Unicode Data Files.
+
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 1991-2026 Unicode, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE 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 OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+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 USE OR PERFORMANCE OF THE DATA FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.
+
+Unicode data used by Homoglyph:
+
+- UTS #39 confusables.txt, Unicode 17.0.0
+  https://www.unicode.org/Public/security/17.0.0/confusables.txt
+- UCD PropertyValueAliases.txt, Unicode 17.0.0
+  https://www.unicode.org/Public/17.0.0/ucd/PropertyValueAliases.txt
+- UCD Scripts.txt, Unicode 17.0.0
+- UCD ScriptExtensions.txt, Unicode 17.0.0
+- UCD DerivedCoreProperties.txt, Unicode 17.0.0
+
+Full Unicode terms: https://www.unicode.org/license.txt

package/README.md

@@ -0,0 +1,143 @@
+# Homoglyph
+
+Unicode-aware detection of visually confusable domain names.
+
+Homoglyph is a multi-language, standards-based library for spotting **Unicode homoglyph / homograph** structure in **domain names**, using [Unicode UTS #39](https://www.unicode.org/reports/tr39/) **17.0.0**.
+
+```text
+paypal.com
+раypal.com
+```
+
+Those strings are not the same domain. The second mixes Cyrillic letters that UTS #39 maps as confusable with Latin.
+
+It is for developers who accept domains through email fields, URL fields, registration forms, and similar inputs.
+
+## Implementations
+
+One GitHub repository, [`ipfy/Homoglyph`](https://github.com/ipfy/Homoglyph), ships native packages:
+
+| Language | Package | Install |
+| --- | --- | --- |
+| JavaScript | npm `@ipfy/homoglyph` | `npm install @ipfy/homoglyph` |
+| Python | PyPI `ipfy-homoglyph` | `pip install ipfy-homoglyph` |
+| PHP | Packagist `ipfy/homoglyph` | `composer require ipfy/homoglyph` |
+
+All three implement the same Homoglyph specification (see `docs/DESIGN.md` and `docs/ARCHITECTURE.md`), the same Unicode 17.0.0 confusable data, and the shared corpus in `conformance/cases/`.
+
+JavaScript additionally provides browser `warn()` / `reject()` helpers. Python and PHP provide the core `detect()` API only.
+
+## What it is — and is not
+
+The **security boundary is the domain**. Email local-parts and URL paths, queries, and fragments are not treated as hostname evidence.
+
+| Observation | Meaning |
+| --- | --- |
+| Unicode in a domain | Not malicious. IDNs are legitimate. |
+| Non-Latin | Not malicious. |
+| Punycode / `xn--` | Not malicious. Valid A-labels are decoded, then analyzed. |
+| Mixed script | Not automatically malicious. |
+| `detected: true` | A UTS #39-relevant issue worth reporting |
+| `rejectable: true` | High-confidence finding suitable for hard enforcement |
+
+Homoglyph does **not** decide whether a domain is a phishing site. It is not a blacklist, reputation service, DNS client, or TLD policy engine.
+
+## JavaScript (npm)
+
+```bash
+npm install @ipfy/homoglyph
+```
+
+```js
+import Homoglyph from '@ipfy/homoglyph';
+
+const result = Homoglyph.detect('раypal.com');
+if (result.detected) {
+  console.log(result.reason, result.domain, result.rejectable);
+}
+```
+
+CDN (IIFE, `globalThis.Homoglyph`):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ipfy/homoglyph/dist/homoglyph.min.js"></script>
+```
+
+Browser-only helpers: `Homoglyph.warn(input)` and `Homoglyph.reject(input)`. See below. There is no `init()`.
+
+## Python (PyPI)
+
+```bash
+pip install ipfy-homoglyph
+```
+
+```python
+import homoglyph
+
+result = homoglyph.detect("раypal.com")
+if result.detected:
+    print(result.reason, result.domain, result.rejectable)
+```
+
+## PHP (Packagist)
+
+Requires PHP 8.1+ and `ext-intl` (Unicode NFC/NFD via `Normalizer`).
+
+```bash
+composer require ipfy/homoglyph
+```
+
+```php
+use IPfy\Homoglyph\Homoglyph;
+
+$result = Homoglyph::detect('раypal.com');
+if ($result->detected) {
+    echo $result->reason, ' ', $result->domain;
+}
+```
+
+## Email and URL behavior
+
+```text
+user@раypal.com                 → analyze раypal.com
+mаnοj@paypal.com               → domain paypal.com; not rejectable
+https://раypal.com/login        → analyze раypal.com
+https://example.com/раypal     → path ignored
+https://example.com/?q=раypal  → query ignored
+https://example.com/#раypal    → fragment ignored
+пример.com                     → labels analyzed independently (not mixed-script)
+```
+
+## Punycode / IDNA
+
+Valid `xn--` A-labels are **decoded** and then analyzed. Punycode itself is not evidence of malice. Successful Punycode decoding is **not** full IDNA validation.
+
+## Unicode
+
+| Item | Value |
+| --- | --- |
+| Unicode / UTS #39 | 17.0.0 |
+| Source of truth | `unicode/` in this repository |
+| Runtime download | none |
+
+Refresh generated maps with `npm run generate` (writes JavaScript, Python, and PHP runtime data from the same files).
+
+## JavaScript `warn()` / `reject()`
+
+These exist only in the JavaScript browser build. They attach form metadata or constraint validation from `detect()`. Visitor-facing `reject()` messages are ordinary validation text, not “phishing” warnings.
+
+## Development
+
+```bash
+npm install
+npm run generate
+npm test
+npm run build
+
+cd python && python -m build && pytest
+cd php && composer install && vendor/bin/phpunit
+```
+
+## License
+
+MIT. Unicode data: Unicode License V3 (see `NOTICE`).