Hashid

Hashid. Hashid is a small open-source library that converts numerical identifiers, such as database primary keys, into short, unique, and non-sequential strings. It is primarily used to obfuscate IDs in public-facing contexts like URLs, providing a layer of security and user-friendliness compared to exposing raw integers. The library is designed to avoid generating common profanities and supports customization of the output alphabet and length. It is implemented in numerous programming languages and is widely used in web development for applications ranging from YouTube-like video IDs to referral codes.

Overview

The library was created to address the common web development issue where exposing incremental database IDs can reveal sensitive information about data volume and growth. Unlike traditional cryptographic hash functions like MD5 or SHA-256, it is not designed for security or collision resistance but for reversible encoding. Its core functionality is similar to systems used by platforms like YouTube for their video identifiers and by Bitly for generating short links. The algorithm ensures the output is non-sequential, making it difficult to guess adjacent IDs, and allows for the use of a custom salt to generate unique encodings for different applications or deployments.

Features

A key feature is its ability to avoid generating strings containing common profanities in the English language by default, which is crucial for public-facing applications. The output length is not fixed and will vary depending on the input number and the configured alphabet, allowing for compact representations of large integers. It supports the use of a custom salt, ensuring that the same number encodes to different strings in different projects, enhancing security through obscurity. The library also allows developers to specify a minimum hash length to ensure a consistent appearance, and it can decode the generated string back to the original number, making it a true bidirectional encoder.

Algorithm

The algorithm operates by interpreting the input number in a base equal to the length of a chosen alphabet, which by default consists of consonant and vowel characters arranged to avoid spelling common words. It uses a custom salt to shuffle this alphabet deterministically, ensuring unique encoding per salt. The process is fundamentally a modified version of a bijective function or a numeral system with a custom character set, similar in concept to Base64 encoding but with a focus on readability and obfuscation. It does not involve complex cryptographic operations like those in SHA-3 or the Feistel cipher structure, keeping it lightweight and fast. The implementation includes checks to prevent the generation of unwanted substrings, iterating through the encoding process if a forbidden pattern is detected.

Implementations

The original reference implementation was written in JavaScript, but the library has been ported to a vast array of other programming languages and environments. These include Python, Ruby, Java, PHP, Go, C#, Swift, Kotlin, and Dart, among others. Many of these ports are available via standard package managers such as npm, PyPI, RubyGems, and Maven. The consistency across implementations ensures that a hash generated in a backend service using Node.js can be reliably decoded by a frontend application written in Python or a mobile app using Swift.

Usage examples

A common use case is in RESTful API design, where resource endpoints use a Hashid string instead of an integer, such as `/users/k9NG7` instead of `/users/12345`. Video sharing platforms, inspired by the approach of YouTube, may use it to generate unique public IDs for uploaded content. E-commerce applications often employ it to generate obfuscated order numbers or referral codes for sharing on social media platforms like Twitter or Facebook. It is also utilized in analytics and marketing tools to create trackable, non-incremental campaign identifiers, and within web frameworks like Ruby on Rails or Django to prettify URLs without relying on database sequence numbers. Category:Cryptographic software Category:Web development