Deterministic ID Encoder

A library for encoding numeric IDs into alphanumeric strings with built-in validation through checksums. Available for both JavaScript and PHP.

Features

• Deterministic encoding: Same ID always produces the same output
• Configurable minimum length: Control the length of your encoded strings
• Checksum validation: Detect tampering and validate encoded IDs
• Customizable character set: Use your preferred character set for encoding
• Language support: Available in JavaScript (Node.js) and PHP

Usage

JavaScript

const DeterministicIdEncoder = require('./encoder');

// Initialize the encoder with options
const encoder = new DeterministicIdEncoder({
  minLength: 10,
  secret: 'your-very-secure-secret-key-here',
  alphabet: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
  checksumLength: 2
});

// Encode a numeric ID
const encodedId = encoder.encode(12345);
console.log(encodedId); // e.g. "4DpQ7W3xZaB"

// Decode back to numeric
const decodedId = encoder.decode(encodedId);
console.log(decodedId); // 12345

PHP

<?php
require_once 'encoder.php';

// Initialize the encoder with options
$encoder = new DeterministicIdEncoder([
  'minLength' => 10,
  'secret' => 'your-very-secure-secret-key-here',
  'alphabet' => '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
  'checksumLength' => 2
]);

// Encode a numeric ID
$encodedId = $encoder->encode(12345);
echo $encodedId; // e.g. "4DpQ7W3xZaB"

// Decode back to numeric
$decodedId = $encoder->decode($encodedId);
echo $decodedId; // 12345

Configuration Options

Option	Description	Default
minLength	Minimum length of encoded IDs	10
secret	Secret key used for padding and checksum generation	"default-secret-key-please-change"
alphabet	Character set used for encoding	"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
checksumLength	Number of characters used for checksum	2

How It Works

1. Base Conversion: Numeric IDs are converted to the specified character set (base)
2. Deterministic Padding: If the resulting string is shorter than the minimum length, it's padded using a deterministic algorithm based on the ID and secret key
3. Checksum Generation: A checksum is added to verify the integrity of the encoded ID
4. Decoding: The process is reversed during decoding, with checksum validation to ensure the ID hasn't been tampered with

Security Considerations

• Always change the default secret key to a secure, random value
• The longer the checksum length, the more secure but longer the encoded ID
• This library is designed for obfuscation and ID shortening, not encryption - don't use it to hide sensitive information

Use Cases

• Creating shorter, more user-friendly IDs for URLs
• Obfuscating sequential database IDs
• Creating verification codes with built-in validation

License

MIT License