@marslanmustafa/input-shield 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Arslan
+
+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/NODEMAILER.md

@@ -0,0 +1,144 @@
+## Nodemailer Integration
+
+`input-shield` works as the validation layer **before** content reaches Nodemailer.
+
+> **Why this matters:** Nodemailer has zero content validation — it will send spam,
+> profanity, or malicious URLs without throwing any error. Validation is 100% your
+> responsibility before calling `sendMail()`.
+
+### Install
+
+```bash
+npm install @marslanmustafa/input-shield nodemailer
+npm install --save-dev @types/nodemailer
+```
+
+---
+
+### Basic contact form
+
+```typescript
+import nodemailer from 'nodemailer';
+import { createValidator } from '@marslanmustafa/input-shield';
+
+// ─── Transporter setup ────────────────────────────────────────────────────────
+const transporter = nodemailer.createTransport({
+  host: process.env.SMTP_HOST,
+  port: 587,
+  auth: {
+    user: process.env.SMTP_USER,
+    pass: process.env.SMTP_PASS,
+  },
+});
+
+// ─── Validators ───────────────────────────────────────────────────────────────
+const nameValidator = createValidator()
+  .field('Name')
+  .min(2).max(60)
+  .noProfanity()
+  .noGibberish({ sensitivity: 'normal' })
+  .noLowQuality();
+
+const subjectValidator = createValidator()
+  .field('Subject')
+  .min(5).max(150)
+  .noProfanity()
+  .noSpam();
+
+const messageValidator = createValidator()
+  .field('Message')
+  .min(10).max(2000)
+  .noProfanity()
+  .noSpam();   // blocks: URLs, "free money", "buy now", "viagra", etc.
+
+// ─── Send function ────────────────────────────────────────────────────────────
+interface ContactFormData {
+  name: string;
+  email: string;
+  subject: string;
+  message: string;
+}
+
+export async function sendContactEmail(data: ContactFormData): Promise<void> {
+  // Validate every field BEFORE touching Nodemailer.
+  // If any check fails, throw immediately — sendMail() is never called.
+  const checks = [
+    nameValidator.validate(data.name),
+    subjectValidator.validate(data.subject),
+    messageValidator.validate(data.message),
+  ];
+
+  for (const result of checks) {
+    if (!result.isValid) {
+      // result.reason → 'profanity' | 'spam' | 'gibberish' | ...
+      // result.message → "Message: appears to contain spam."
+      throw new Error(result.message);
+    }
+  }
+
+  // ✅ All fields are clean — safe to send
+  await transporter.sendMail({
+    from: `"${data.name}" <${process.env.SMTP_USER}>`,
+    replyTo: data.email,
+    to: process.env.CONTACT_EMAIL,
+    subject: data.subject,
+    text: data.message,
+  });
+}
+```
+
+---
+
+### Express route example
+
+```typescript
+import express from 'express';
+import { sendContactEmail } from './mailer';
+
+const router = express.Router();
+
+router.post('/contact', async (req, res) => {
+  try {
+    await sendContactEmail(req.body);
+    res.json({ success: true, message: 'Message sent.' });
+  } catch (err) {
+    // Validation errors and mail errors both surface here
+    res.status(400).json({
+      success: false,
+      message: err instanceof Error ? err.message : 'Failed to send message.',
+    });
+  }
+});
+
+export default router;
+```
+
+---
+
+### What gets blocked before it reaches Nodemailer
+
+| Input | Reason blocked |
+|---|---|
+| `"Buy vi4gra now!"` | `spam` — leet-evaded keyword |
+| `"Check https://spam.com"` | `spam` — URL detected |
+| `"Win fr33 m0n3y!"` | `spam` — leet-evaded phrase |
+| `"sh!t service"` | `profanity` — leet-evaded |
+| `"аsshole"` (Cyrillic а) | `profanity` — homoglyph bypass caught |
+| `"asdfghjkl"` | `gibberish` — keyboard mash |
+| `"test"` | `low_effort` — placeholder value |
+
+---
+
+### Without input-shield — what Nodemailer does
+
+```typescript
+// ❌ Nodemailer sends this with NO error — zero content validation
+await transporter.sendMail({
+  to: 'you@example.com',
+  subject: 'Buy vi4gra now!!!',
+  text: 'Win fr33 m0n3y at https://spam.com click here now',
+});
+// → Delivered. No exception. No warning.
+```
+
+`input-shield` is the layer that stops this **before** `sendMail()` is ever called.

package/README.md

@@ -0,0 +1,239 @@
+# @marslanmustafa/input-shield
+
+[![npm version](https://img.shields.io/npm/v/@marslanmustafa/input-shield.svg)](https://www.npmjs.com/package/@marslanmustafa/input-shield)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@marslanmustafa/input-shield)](https://bundlephobia.com/package/@marslanmustafa/input-shield)
+[![test coverage](https://img.shields.io/codecov/c/github/marslanmustafa/input-shield)](https://codecov.io/gh/marslanmustafa/input-shield)
+[![license](https://img.shields.io/npm/l/@marslanmustafa/input-shield)](LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
+
+> **One install. No config. Clean inputs.**
+>
+> Profanity · Spam · Gibberish · Leet-speak · Homoglyphs — all in one zero-dependency TypeScript package.
+
+---
+
+## Why @marslanmustafa/input-shield?
+
+| Problem | Old way (3+ packages) | @marslanmustafa/input-shield |
+|---|---|---|
+| Block profanity | `npm i obscenity` | ✅ built in |
+| Catch `f.u.c.k` / `f@ck` / `ｆｕｃｋ` | Manual regex + leet map | ✅ 3-stage normalization |
+| Catch Cyrillic `аss` (homoglyph bypass) | Nobody does this | ✅ NFKC + homoglyph map |
+| Block spam URLs | `npm i validator` | ✅ built in |
+| Detect keyboard mash | Hand-rolled heuristics | ✅ `loose/normal/strict` scale |
+| Zod integration | 20 lines of glue code | ✅ `import from '@marslanmustafa/input-shield/zod'` |
+| TypeScript types | Often partial | ✅ first-class, discriminated union |
+| Tree-shakeable | Rarely | ✅ every function importable alone |
+
+---
+
+## Install
+
+```bash
+npm install @marslanmustafa/@marslanmustafa/input-shield
+pnpm add @marslanmustafa/@marslanmustafa/input-shield
+yarn add @marslanmustafa/@marslanmustafa/input-shield
+```
+
+---
+
+## Quick start
+
+```typescript
+import { createValidator } from '@marslanmustafa/input-shield';
+
+const usernameValidator = createValidator()
+  .field('Username')
+  .min(3).max(30)
+  .noProfanity()
+  .noGibberish({ sensitivity: 'strict' })
+  .noSpam();
+
+const result = usernameValidator.validate(userInput);
+
+if (!result.isValid) {
+  console.log(result.reason);   // 'profanity' | 'gibberish' | 'spam' | ...
+  console.log(result.message);  // "Username: contains inappropriate language."
+}
+```
+
+---
+
+## Presets (zero-config)
+
+```typescript
+import {
+  validateUsername,
+  validateBio,
+  validateShortText,
+  validateLongText,
+  validateSearchQuery,
+} from '@marslanmustafa/input-shield';
+
+validateUsername('alice_dev');     // { isValid: true }
+validateUsername('f4ck3r');        // { isValid: false, reason: 'profanity', message: '...' }
+validateBio('Software engineer from Lahore'); // { isValid: true }
+validateShortText('test');         // { isValid: false, reason: 'low_effort', message: '...' }
+```
+
+---
+
+## Integrations
+
+- 📧 [Nodemailer — validate email content before sending](./NODEMAILER.md)
+## Fluent builder API
+
+```typescript
+import { createValidator } from '@marslanmustafa/input-shield';
+
+createValidator()
+  .field('Product Name')    // shown in error messages
+  .min(2).max(60)           // length bounds
+  .noProfanity()            // catches leet, homoglyphs, dots (f.u.c.k), fullwidth (ｆｕｃｋ)
+  .noSpam()                 // keywords + URLs (on raw text — not destroyed by normalization)
+  .noGibberish({            // sensitivity: 'loose' | 'normal' | 'strict'
+    sensitivity: 'normal',  // default — good for most fields
+  })
+  .noLowQuality()           // exact matches (test, asdf), excessive symbols, low letter ratio
+  .noRepeatedWords()        // catches "cat cat cat" (ignores stop words)
+  .allow('nginx', 'kubectl') // allowlist bypasses ALL checks (brand names, tech terms)
+  .custom(                  // custom rule — return true to BLOCK
+    t => t.startsWith('@'),
+    'custom',
+    'names cannot start with @'
+  )
+  .validate(text);          // → ValidationResult
+```
+
+---
+
+## Zod integration
+
+```bash
+# zod is a peer dependency — install it separately
+npm install zod @marslanmustafa/input-shield
+```
+
+```typescript
+import { z } from 'zod';
+import { shieldString, zodUsername, zodBio } from '@marslanmustafa/input-shield/zod';
+
+// Preset schemas
+const schema = z.object({
+  username: zodUsername(),
+  bio: zodBio(),
+});
+
+// Custom configured schema
+const customSchema = z.object({
+  productName: shieldString(v =>
+    v.field('Product Name').min(2).max(60).noProfanity().noSpam()
+  ),
+});
+
+// Usage with react-hook-form + zod resolver — zero extra code
+```
+
+---
+
+## How the normalization pipeline works
+
+This is the core innovation. Input is processed through 3 stages before any check runs:
+
+```
+Input: "P.0.r.n" or "ｆｕｃｋ" or "аss" (Cyrillic а) or "f@ck"
+       │
+       ▼ Stage 1: Unicode NFKC
+         Collapses fullwidth, math-bold, ligatures, zero-width chars
+         "ｆｕｃｋ" → "fuck"  |  "𝐅𝐔𝐂𝐊" → "FUCK"
+       │
+       ▼ Stage 2: Separator stripping
+         Removes dots/dashes between single chars
+         "P.0.r.n" → "P0rn"  |  "f-u-c-k" → "fuck"
+       │
+       ▼ Stage 3: Homoglyph map (Cyrillic/Greek/Armenian → Latin)
+         "аss" (Cyrillic а U+0430) → "ass"
+         "ρorn" (Greek ρ) → "porn"
+       │
+       ▼ Stage 4: Leet-speak substitution
+         "0" → "o", "@" → "a", "$" → "s", "!" → "i" …
+         "f@ck" → "fack"  |  "@ss" → "ass"
+       │
+       ▼ Skeleton: "fuck" / "ass" / "porn"
+         Pattern matching runs here ───────────────► BLOCKED
+         Error messages reference ORIGINAL input ──► "f@ck"
+```
+
+---
+
+## API Reference
+
+### `createValidator(): InputShieldValidator`
+Returns a new fluent builder instance.
+
+### Builder methods
+
+| Method | Description |
+|---|---|
+| `.field(name)` | Set field label for error messages |
+| `.min(n)` | Minimum length. Default: 2 |
+| `.max(n)` | Maximum length. Default: 500 |
+| `.allow(...words)` | Allowlist — bypasses all checks |
+| `.noProfanity()` | Block profanity (all evasions caught) |
+| `.noSpam()` | Block spam keywords and URLs |
+| `.noGibberish(opts?)` | Block keyboard mash. `opts.sensitivity`: `'loose'` / `'normal'` / `'strict'` |
+| `.noLowQuality()` | Block exact low-effort matches, excessive symbols, low letter ratio |
+| `.noRepeatedWords()` | Block inputs with many repeated content words |
+| `.custom(fn, reason, msg)` | Custom rule. `fn(text) => true` to BLOCK |
+| `.validate(text)` | Run all checks. Returns `ValidationResult` |
+| `.validateOrThrow(text)` | Throws on invalid input. Useful in Zod `.superRefine()` |
+
+### `ValidationResult` (discriminated union)
+
+```typescript
+type ValidationResult =
+  | { isValid: true }
+  | { isValid: false; reason: FailReason; message: string };
+
+type FailReason =
+  | 'empty' | 'too_short' | 'too_long'
+  | 'profanity' | 'spam'
+  | 'gibberish' | 'low_effort' | 'repeating_chars' | 'excessive_symbols'
+  | 'homoglyph_attack' | 'custom';
+```
+
+### Sensitivity scale
+
+| Sensitivity | Consonant run | Vowel ratio check | Best for |
+|---|---|---|---|
+| `'loose'` | 7+ in a row | ≥ 12 chars, < 5% vowels | Bio, non-English names |
+| `'normal'` | 6+ in a row | ≥ 8 chars, < 10% vowels | Most fields |
+| `'strict'` | 5+ in a row | ≥ 6 chars, < 15% vowels | Usernames, display names |
+
+---
+
+## Tree-shaking
+
+Every module is independently importable:
+
+```typescript
+import { toSkeleton } from '@marslanmustafa/input-shield';           // normalization only
+import { containsProfanity } from '@marslanmustafa/input-shield';     // profanity only
+import { isGibberish } from '@marslanmustafa/input-shield';           // gibberish only
+```
+
+---
+
+## Bundle size
+
+| Import | Size (minzipped) |
+|---|---|
+| `createValidator` (full builder) | ~4 KB |
+| `containsProfanity` only | ~1.5 KB |
+| `@marslanmustafa/input-shield/zod` | +1 KB (zod external) |
+
+---
+
+## License
+
+MIT © [Muhammad Arslan](https://marslanmustafa.com)

package/dist/builder-C10YQjbV.d.cts

@@ -0,0 +1,123 @@
+type FailReason = 'empty' | 'too_short' | 'too_long' | 'profanity' | 'spam' | 'gibberish' | 'low_effort' | 'repeating_chars' | 'excessive_symbols' | 'homoglyph_attack' | 'custom';
+type ValidationResult = {
+    isValid: true;
+} | {
+    isValid: false;
+    reason: FailReason;
+    message: string;
+};
+type GibberishSensitivity = 'loose' | 'normal' | 'strict';
+interface ValidationOptions {
+    /** Display name used in error messages. Default: "Input" */
+    fieldName?: string;
+    /** Minimum character length (post-trim). Default: 2 */
+    minLength?: number;
+    /** Maximum character length. Default: 500 */
+    maxLength?: number;
+    /** Controls how aggressively gibberish is flagged. Default: "normal" */
+    gibberishSensitivity?: GibberishSensitivity;
+    /** Skip gibberish check entirely. Useful for short codes, IDs, non-English. */
+    skipGibberishCheck?: boolean;
+    /** Skip repeated-word detection. Useful for long-form natural language. */
+    skipRepeatWordCheck?: boolean;
+    /** Extra words/phrases to block (exact, case-insensitive). */
+    customBlocklist?: string[];
+    /** Strings always allowed, bypassing all checks (e.g. brand names, acronyms). */
+    allowlist?: string[];
+}
+
+/**
+ * builder.ts
+ *
+ * Fluent builder API — the primary way developers use input-shield.
+ *
+ * Usage:
+ *   const validator = createValidator()
+ *     .field('Username')
+ *     .min(3).max(30)
+ *     .noProfanity()
+ *     .noGibberish({ sensitivity: 'strict' })
+ *     .noSpam()
+ *     .allow('nginx', 'kubectl');
+ *
+ *   const result = validator.validate(userInput);
+ *   if (!result.isValid) console.error(result.reason, result.message);
+ *
+ * Design principles:
+ *   - Each check is opt-in via a chain method (not a giant options object)
+ *   - Checks run in declaration order (you control the priority)
+ *   - Returns typed FailReason, not just a boolean
+ *   - Allowlist bypasses ALL checks (brand names, abbreviations, etc.)
+ *   - Custom check via .custom() for domain-specific rules
+ */
+
+declare class InputShieldValidator {
+    private _fieldName;
+    private _min;
+    private _max;
+    private _allowlist;
+    private _checks;
+    private _spamCheck;
+    /** Set the field label used in error messages */
+    field(name: string): this;
+    /** Minimum character length (post-trim). Default: 2 */
+    min(n: number): this;
+    /** Maximum character length. Default: 500 */
+    max(n: number): this;
+    /**
+     * Add strings that always pass validation, regardless of other checks.
+     * Useful for brand names, tech terms, or known-good short strings.
+     *   .allow('nginx', 'kubectl', 'QA', 'IT')
+     */
+    allow(...words: string[]): this;
+    /** Block profanity, including leet-speak and homoglyph evasions */
+    noProfanity(): this;
+    /**
+     * Block spam keywords and URLs.
+     * Note: URL detection uses the raw string internally (not the skeleton),
+     * so you don't need to worry about URLs being missed.
+     */
+    noSpam(): this;
+    /**
+     * Block gibberish / keyboard mash.
+     *
+     * @param options.sensitivity
+     *   'loose'  — only catches extreme mashing (7+ consonants). Safe for names.
+     *   'normal' — default. Catches most mashing while allowing tech words.
+     *   'strict' — also catches low vowel-ratio words. Best for usernames.
+     */
+    noGibberish(options?: {
+        sensitivity?: GibberishSensitivity;
+    }): this;
+    /** Block inputs that are structurally low quality (too many symbols, too few letters) */
+    noLowQuality(): this;
+    /** Block inputs that repeat content words excessively */
+    noRepeatedWords(): this;
+    /**
+     * Add a custom validation rule.
+     *
+     * @param fn      - Returns true if the input is INVALID (should be blocked)
+     * @param reason  - The FailReason code to return
+     * @param message - Human-readable message (do not include fieldName, it's prepended)
+     *
+     * @example
+     * .custom(t => t.includes('@'), 'custom', 'product names cannot contain @')
+     */
+    custom(fn: (text: string) => boolean, reason: FailReason, message: string): this;
+    validate(text: string): ValidationResult;
+    /**
+     * Validate and throw if invalid. Useful in form libraries / Zod .superRefine().
+     * @throws Error with the validation message
+     */
+    validateOrThrow(text: string): void;
+}
+/**
+ * Create a new fluent validator.
+ * No `new` keyword needed.
+ *
+ * @example
+ * const v = createValidator().field('Username').min(3).noProfanity().noGibberish();
+ */
+declare function createValidator(): InputShieldValidator;
+
+export { type FailReason as F, type GibberishSensitivity as G, InputShieldValidator as I, type ValidationResult as V, type ValidationOptions as a, createValidator as c };

package/dist/builder-C10YQjbV.d.ts

@@ -0,0 +1,123 @@
+type FailReason = 'empty' | 'too_short' | 'too_long' | 'profanity' | 'spam' | 'gibberish' | 'low_effort' | 'repeating_chars' | 'excessive_symbols' | 'homoglyph_attack' | 'custom';
+type ValidationResult = {
+    isValid: true;
+} | {
+    isValid: false;
+    reason: FailReason;
+    message: string;
+};
+type GibberishSensitivity = 'loose' | 'normal' | 'strict';
+interface ValidationOptions {
+    /** Display name used in error messages. Default: "Input" */
+    fieldName?: string;
+    /** Minimum character length (post-trim). Default: 2 */
+    minLength?: number;
+    /** Maximum character length. Default: 500 */
+    maxLength?: number;
+    /** Controls how aggressively gibberish is flagged. Default: "normal" */
+    gibberishSensitivity?: GibberishSensitivity;
+    /** Skip gibberish check entirely. Useful for short codes, IDs, non-English. */
+    skipGibberishCheck?: boolean;
+    /** Skip repeated-word detection. Useful for long-form natural language. */
+    skipRepeatWordCheck?: boolean;
+    /** Extra words/phrases to block (exact, case-insensitive). */
+    customBlocklist?: string[];
+    /** Strings always allowed, bypassing all checks (e.g. brand names, acronyms). */
+    allowlist?: string[];
+}
+
+/**
+ * builder.ts
+ *
+ * Fluent builder API — the primary way developers use input-shield.
+ *
+ * Usage:
+ *   const validator = createValidator()
+ *     .field('Username')
+ *     .min(3).max(30)
+ *     .noProfanity()
+ *     .noGibberish({ sensitivity: 'strict' })
+ *     .noSpam()
+ *     .allow('nginx', 'kubectl');
+ *
+ *   const result = validator.validate(userInput);
+ *   if (!result.isValid) console.error(result.reason, result.message);
+ *
+ * Design principles:
+ *   - Each check is opt-in via a chain method (not a giant options object)
+ *   - Checks run in declaration order (you control the priority)
+ *   - Returns typed FailReason, not just a boolean
+ *   - Allowlist bypasses ALL checks (brand names, abbreviations, etc.)
+ *   - Custom check via .custom() for domain-specific rules
+ */
+
+declare class InputShieldValidator {
+    private _fieldName;
+    private _min;
+    private _max;
+    private _allowlist;
+    private _checks;
+    private _spamCheck;
+    /** Set the field label used in error messages */
+    field(name: string): this;
+    /** Minimum character length (post-trim). Default: 2 */
+    min(n: number): this;
+    /** Maximum character length. Default: 500 */
+    max(n: number): this;
+    /**
+     * Add strings that always pass validation, regardless of other checks.
+     * Useful for brand names, tech terms, or known-good short strings.
+     *   .allow('nginx', 'kubectl', 'QA', 'IT')
+     */
+    allow(...words: string[]): this;
+    /** Block profanity, including leet-speak and homoglyph evasions */
+    noProfanity(): this;
+    /**
+     * Block spam keywords and URLs.
+     * Note: URL detection uses the raw string internally (not the skeleton),
+     * so you don't need to worry about URLs being missed.
+     */
+    noSpam(): this;
+    /**
+     * Block gibberish / keyboard mash.
+     *
+     * @param options.sensitivity
+     *   'loose'  — only catches extreme mashing (7+ consonants). Safe for names.
+     *   'normal' — default. Catches most mashing while allowing tech words.
+     *   'strict' — also catches low vowel-ratio words. Best for usernames.
+     */
+    noGibberish(options?: {
+        sensitivity?: GibberishSensitivity;
+    }): this;
+    /** Block inputs that are structurally low quality (too many symbols, too few letters) */
+    noLowQuality(): this;
+    /** Block inputs that repeat content words excessively */
+    noRepeatedWords(): this;
+    /**
+     * Add a custom validation rule.
+     *
+     * @param fn      - Returns true if the input is INVALID (should be blocked)
+     * @param reason  - The FailReason code to return
+     * @param message - Human-readable message (do not include fieldName, it's prepended)
+     *
+     * @example
+     * .custom(t => t.includes('@'), 'custom', 'product names cannot contain @')
+     */
+    custom(fn: (text: string) => boolean, reason: FailReason, message: string): this;
+    validate(text: string): ValidationResult;
+    /**
+     * Validate and throw if invalid. Useful in form libraries / Zod .superRefine().
+     * @throws Error with the validation message
+     */
+    validateOrThrow(text: string): void;
+}
+/**
+ * Create a new fluent validator.
+ * No `new` keyword needed.
+ *
+ * @example
+ * const v = createValidator().field('Username').min(3).noProfanity().noGibberish();
+ */
+declare function createValidator(): InputShieldValidator;
+
+export { type FailReason as F, type GibberishSensitivity as G, InputShieldValidator as I, type ValidationResult as V, type ValidationOptions as a, createValidator as c };