README.md

Seeded-Hashids

Generate seeded Hashids that is unique per seed.

Seeded-Hashids is an easy to use library to generate seeded Hashids which is unique to a seed that can be based on a user or group. Hide the raw ids, hex strings, objectids or uuids from end users and reduces the number of database calls that check for valid or existing ids.

Works well with databases that has numeric keys or hex strings. Your database will contain only the original ids as there is no need to store the encoded versions. UUIDs and MongoDB's ObjectIDs are hex strings.

An example is to generate Hashids that are unique to a particular application. Even if multiple applications shared their userids with each other, the users could not be correlated or identified by their userids.

Sample Scenario

Encoding the userids and using their actual userid as a seed.
The userids are unique and never revealed to end users.
User A (ID 123)
User B (ID 456)
User C (ID 789)

Application A sees User B as 'zxcqwe' and sees User C as 'bnmrty'
Application B sees User A as 'qweasd' and sees User C as 'rtyjkl'
Application C sees User A as 'fghzxc' and sees User B as 'asdiop'

'asdiop' is supposedly only visible to Application C.
If Application A decodes 'asdiop', it decodes to an empty string.

Getting started

Install Seeded-Hashids via:

• npm: npm install --save seeded-hashids
• yarn: yarn add seeded-hashids

Sample code:

const seededHashids = require('seeded-hashids');
const ObjectId = require('mongoose').Types.ObjectId;
const scopes = [
  {scope: 'user', salt: 'some-salt'}
];

seededHashids.initialize({scopes: scopes, objectId: ObjectId});

let encoded, decoded;

// Encoding hex strings
encoded = seededHashids.encodeHex('user', 'abcd1234');
decoded = seededHashids.decodeHex('user', encoded);
console.log(encoded); // 'bNVA3Q9g'
console.log(decoded); // 'abcd1234'

// Encoding hex strings with seed
encoded = seededHashids.encodeHex('user', 'abcd1234', 'unique-seed');
decoded = seededHashids.decodeHex('user', encoded, 'unique-seed');
console.log(encoded); // 'S4RTRZ2L'
console.log(decoded); // 'abcd1234'

// If a wrong seed is used for decodeHex, will decode to a different output
decoded = seededHashids.decodeHex('user', encoded, 'wrong-seed');
console.log(decoded); // '' (Empty string)

// Decoding ObjectIds, same as hex but needs to be 24 characters hex string
encoded = seededHashids.encodeHex('user', 'abcd1234abcd1234abcd1234');
decoded = seededHashids.decodeObjectId('user', encoded);
console.log(encoded); // '4Wg453PYPrdhAEdyeMYWpm'
console.log(decoded); // ObjectId('abcd1234abcd1234abcd1234')

// Decoding ObjectIds with seed, same as hex but needs to be 24 characters hex string
encoded = seededHashids.encodeHex('user', 'abcd1234abcd1234abcd1234', 'unique-seed');
decoded = seededHashids.decodeObjectId('user', encoded, 'unique-seed');
console.log(encoded); // 'QX3Bu2pNSTnPEZFg6sW5EY'
console.log(decoded); // ObjectId('abcd1234abcd1234abcd1234')

// Encoding positive integers
encoded = seededHashids.encode('user', 12345678);
decoded = seededHashids.decode('user', encoded);
console.log(encoded); // 'nY9AyaDn'
console.log(decoded); // 12345678

// Encoding positive integers with seed
encoded = seededHashids.encode('user', 12345678, 'unique-seed');
decoded = seededHashids.decode('user', encoded, 'unique-seed');
console.log(encoded); // 'aNq4PsAx'
console.log(decoded); // 12345678

// If a wrong seed is used for decode, will decode to a different output
decoded = seededHashids.decode('user', encoded, 'wrong-seed');
console.log(decoded); // NaN (Different output)

// Encoding array of positive integers
encoded = seededHashids.encode('user', [1,2,3,4,5,6,7,8]);
decoded = seededHashids.decode('user', encoded);
console.log(encoded); // '6ZsyFeUKc5fahqS5'
console.log(decoded); // [1,2,3,4,5,6,7,8]

// Encoding array of positive integers with seed
encoded = seededHashids.encode('user', [1,2,3,4,5,6,7,8], 'unique-seed');
decoded = seededHashids.decode('user', encoded, 'unique-seed');
console.log(encoded); // '9bzhGs3kHZVJs7wm'
console.log(decoded); // [1,2,3,4,5,6,7,8]

API

initialize (options) : noResult undefined

To set up the required scopes and other parameters.

seededHashids.initialize({
  scopes: scopes,
  charset: charset,
  minOutputLength: minOutputLength,
  shuffleOutput: shuffleOutput,
  objectId: objectId,
  shuffleFunction: shuffleFunction,
  unshuffleFunction: unshuffleFunction
});

options Object

Field	Required	Type	Defaults
scopes	yes	Array	-
charset	no	String	a-z, A-Z, 2-9 without i, I, o, O, 1, 0 to increase readibility
minOutputLength	no	Number	8
shuffleOutput	no	Boolean	true
objectId	no	ObjectId	-
shuffleFunction	no	Function	Built-in shuffle function
unshuffleFunction	no	Function	Built-in unshuffle function

scopes Array

• The array is a list of scope object that contains a scope string and a salt string.
• Each scope could be then name of a class or an object type.
• Scopes have to be unique.
• Salts have to be unique.

let scope = [
  {scope: 'user', salt: 'some-salt'},
  {scope: 'profile', salt: 'another-salt'}
];

charset String (optional)

• This value is passed directly to Hashids.
• A minimum of 16 unique characters are required.

let charset = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789';

minOutputLength Number (optional)

• This value is passed directly to Hashids, which adds padding to reach the length required.

let minOutputLength = 8;

shuffleOutput Boolean (optional)

• This value determines if the output seeded-hashid will be shuffled after encoding and before decoding by Hashids.
• The output is shuffled based on the seed and attempts to prevent decoding using a wrong seed.
• If no seed is provided, the output seeded-hashid will not be shuffled.

let shuffleOutput = true;

objectId Function (optional)

• This object is required only if there is a need to cast the decoding output to an ObjectId using .decodeObjectId.
• Can pass in require('mongoose').Types.ObjectId or require('mongodb').ObjectId or functions.

let objectId = require('mongoose').Types.ObjectId;

shuffleFunction Function (optional)

• Change the shuffle function used.
• The shuffle function needs to accept (inputString, seedString) and returns an outputString.

let shuffleFunction = function(inputString, seedString){
  return require('shuffle-seed').shuffle(inputString.split(''), seedString).join('');
};

unshuffleFunction Function (optional)

• Change the unshuffle function used.
• The unshuffle function needs to accept (inputString, seedString) and returns an outputString.

let unshuffleFunction = function(inputString, seedString){
  return require('shuffle-seed').unshuffle(inputString.split(''), seedString).join('');
};

---

encode (scope, data, [seed]) : seededHashid String

To encode positive numbers.

let userId = seededHashids.encode('user', 12345678);

scope String

• This scope should be the same scope string that was used during initialization.

data Number or Array of Numbers

• The positive number or the array of positive numbers to be encoded.

seed String (optional)

• This seed is used to encode a seeded-hashid that is unique to the seed.

---

encodeHex (scope, hex, [seed]) : seededHashid String

To encode hex strings.

let userId = seededHashids.encodeHex('user', 'abcd1234', 'unique-seed');

scope String

• This scope should be the same scope string that was used during initialization.

hex String

• This hex string to be encoded.

seed String (optional)

• This seed is used to encode a seeded-hashid that is unique to the seed.

---

decode (scope, seededHashid, [seed]) : decodedData Number or Array of Numbers

To decode seeded-hashid into a positive number or an array of positive numbers. Returns NaN if unable to decode.

let userId = seededHashids.decode('user', 'nY9AyaDn', 'unique-seed');

scope String

• This scope should be the same scope string that was used during initialization.

seededHashid String

• This seeded-hashid to be decoded.

seed String (optional)

• This seed is used to decode a seeded-hashid that is unique to the seed.

---

decodeHex (scope, seededHashid, [seed]) : decodedHex String

To decode seeded-hashid into a hex string. Returns an empty string if unable to decode.

let userId = seededHashids.decodeHex('user', 'S4RTRZ2L', 'unique-seed');

scope String

• This scope should be the same scope string that was used during initialization.

seededHashid String

• This seeded-hashid to be decoded.

seed String (optional)

• This seed is used to decode a seeded-hashid that is unique to the seed.

---

decodeObjectId (scope, seededHashid, [seed]) : decodedObjectId ObjectId

To decode seeded-hashid into an objectId. Returns NaN if unable to decode.

let userId = seededHashids.decodeObjectId('user', 'QX3Bu2pNSTnPEZFg6sW5EY', 'unique-seed');

scope String

• This scope should be the same scope string that was used during initialization.

seededHashid String

• This seeded-hashid to be decoded.

seed String (optional)

• This seed is used to decode a seeded-hashid that is unique to the seed.

---

reset () : noResult undefined

To reset seededHashids, needs to initialize() again before usage.

seededHashids.reset();

---

isInitialized () : isInitialized Boolean

To check if seededHashids is initialized.

let isInitialized = seededHashids.isInitialized();

---

getScopes () : scopes Array

To get the string array of scopes.

let scopes = seededHashids.getScopes();

---

getCharset () : charset String

To get the charset string.

let charset = seededHashids.getCharset();

---

getMinOutputLength () : minOutputLength Number

To get the minimum output seeded-hashid length.

let minOutputLength = seededHashids.getMinOutputLength();

---

getShuffleOutput () : shuffleOutput Boolean

To check if the output will be shuffled if a seed is provided.

let shuffleOutput = seededHashids.getShuffleOutput();

---

getObjectId () : objectId Function

To get the objectId function to see if available.

let objectId = seededHashids.getObjectId();

---

getShuffleFunction () : shuffleFunction Function

To get the shuffle function used.

let shuffleFunction = seededHashids.getShuffleFunction();

---

getUnshuffleFunction () : unshuffleFunction Function

To get the unshuffle function used.

let unshuffleFunction = seededHashids.getUnshuffleFunction();

Recommendations

1. Charset should not be too short.
2. Salts should not be too short.
3. Seeds should not be too short. Recommended to use long hex strings such as ObjectIds or UUIDs.
4. Encode longer input hex strings such as ObjectIds or UUIDs.
5. Always validate the output after decoding.
6. The minOutputLength should not be too small.
7. Leave the shuffleOutput as true, which is the default value.
8. Encode and decode as required, recommended for database to contain only original ids or hex strings.

Pitfalls

1. Encoding of an array of numbers is supported but the numbers within are not individually shuffled.
2. Encoding of negative numbers are not supported.
3. Required to pass in the correct type of parameters in order to prevent the encoding of invalid seeded-hashids by accident, such as encoding "[object Object]".
4. It could still be possible for a different seed to decode a seeded-hashid, but it is really rare if the recommendations are followed.
5. Upgrade to a major version after testing as the output seeded-hashids may have changed.
6. Do not use this library as a security tool and do not encode sensitive data. This is not an encryption library.

License

MIT License. See the LICENSE file.