@cttricks/maskid

What It Is

When building web applications and REST APIs, databases typically use auto-incrementing integers for primary keys (1, 2, 3, ...). Exposing raw sequential database IDs in URLs (e.g. /orders/1042 or /users/45) creates significant security and business vulnerabilities:

• Anyone can sequentially enumerate all records to scrape data or discover competitive insights (e.g., how many orders your platform processes per day).
• Direct object reference (IDOR) attacks become trivial to test.

While UUIDs solve enumeration, they are bulky (36 characters), consume extra database index space, and create unwieldy URLs.

I created and published @cttricks/maskid as a lightweight, zero-dependency TypeScript package that provides deterministic, reversible integer obfuscation into friendly alphanumeric strings (e.g. converting 1042 into a short, non-guessable string like xK9mQ).

---

What It Does

• Deterministic & Reversible: Safely encodes sequential integers into short alphanumeric tokens and decodes them back on incoming API requests with zero database lookups.
• Zero Dependencies: Ultra-lightweight footprint with zero external dependencies to keep bundle sizes lean.
• Customizable Salts & Alphabets: Allows projects to supply custom salt strings and character sets so encoded tokens cannot be decoded by third parties using default settings.
• TypeScript First: Fully typed with strict signatures and ESM/CJS compatibility.

---

Installation & Quick Usage

npm i @cttricks/maskid

import { MaskId } from "@cttricks/maskid";

const mask = new MaskId({ salt: "your-secret-salt-key", minLength: 6 });

// Encode database ID for public URL
const publicToken = mask.encode(1042); // "7kX9pQ"

// Decode back to integer in your API handler
const internalId = mask.decode("7kX9pQ"); // 1042

---

Why I Built It & Open Sourced It

I initially designed this algorithm while building high-traffic production SaaS tools at DOTIX. We needed clean, compact public identifiers for resource sharing without replacing integer primary keys across hundreds of existing database tables.

Recognizing that many indie developers and engineering teams face this exact dilemma, I packaged the logic, wrote comprehensive unit test suites, added full TypeScript definitions, and open-sourced it on NPM.

---

Key Learnings & Takeaways

• Simplicity wins in developer utilities: High-frequency utility packages should do one thing exceptionally well with zero dependencies and zero bloat.
• Defense in depth: Obfuscation does not replace robust authorization checks, but preventing trivial ID enumeration closes an enormous class of opportunistic attack vectors.