Obscura

Obscura is a JavaScript library written in TypeScript allowing you to encode and decode strings into UUIDs. Obscura is designed to be simple and easy to use, while also being powerful and flexible. Obscura is not a cryptographic library, and should not be used for security purposes. It is designed for obfuscation and encoding, not encryption. The decryption key necessary to decode a UUID back to its original form is included in localStorage for now. This may change in the future, but the decryption key must be stored somewhere as a UUID is non-reversible.

[!CAUTION] Do not attempt to use Obscura for security purposes. It is not designed for that, and will not work as expected. Obscura is designed for obfuscation and encoding, not encryption. Do not use Obscura to store sensitive information, as it is not secure.

Installation

[!TIP] It might be easier to use Obscura with a bundler, such as Vite, Webpack, or Parcel. This will allow you to use Obscura in a browser environment without having to worry about the complexities of bundling and transpiling your code. If you are using a bundler, you can simply import Obscura as a module and use it in your code.

Bundler

All you need to do to use Obscura in a bundler environment is to install it via npm or yarn, and then import it into your code.

import { Obscura } from "@nightnetwork/obscura";

Static

To use Obscura in a static environment, you'll need to clone the Obscura git repo.

Open your terminal.

Start by cloning the repo:

git clone https://github.com/Night-Libs/Obscura.git

Then, change your current working directory to be the newly created directory Obscura (this might change based on the config you provided the clone command)

cd Obscura

Next, install bun for your machine if you haven't already. You can find the installation instructions on Bun's official website. If you have just freshly installed bun, restart your terminal and renavigate to the Obscura folder.

Next, install the dependencies required by Obscura by running:

bun i

After that, build Obscura by running:

bun run build

You'll find a dist folder in the Obscura directory, which contains the built files.

You can now use Obscura in your static environment by including the obscura.js file in your HTML file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Obscura Example</title>
    <script src="path/to/obscura.js"></script>
  </head>
  <body></body>
</html>

[!IMPORTANT]
Remember to build Obscura before using it in a browser environment without a bundler. You can do this by running bun run build in the root directory. This will create a dist folder with the built files. Copy the obscura.js file from the dist folder to your project and include it in your HTML file.

Usage

In this section, we are assuming we are using a bundler. The instructions are the same for initializing Obscura in a static environment, but you will need to include the obscura.js file in your HTML file as described above.

Firstly, we need to create an instance of Obscura.

Obscura requires a passphrase to be passed in the constructor. You can use your own, or generate a random one using Obscura.genPassphrase(8). You may replace 8 with any number you want, but it is recommended to use a length greater than or equal to 8 for security purposes. The number is the character length of your passphrase.

Obscura uses ESM syntax. Keep that in mind when importing it without a bundler.

The below examples assume you are importing Obscura as Obscura, and not a custom name.

Now that we have our passphrase, we need to initialize the Obscura class.

// assumes passphrase is a variable containing either your generated passphrase or your custom one
const obscura = new Obscura(passphrase);

[!IMPORTANT] The following step is prone to change; please check the Obscura documentation in case the following method changes in a future update.

Next, we need to initialize core values needed for Obscura to work. In this version of Obscura (v1.0.0), we can just do:

// assumes obscura is the instance of Obscura we created earlier
await obscura.init();

[!WARNING] All of Obscura's methods are asynchronous, so you will need to use await when calling them. If you are not using await, you will need to use .then() to handle the promise returned by the method.

Finally, we can use the .encode and .decode methods to encode and decode strings into UUIDs like so:

// assmues input is a string containing the string we want to encode and uuid is the string containing the uuid we want to decode.
const uuid = await obscura.encode(input);
const decoded = await obscura.decode(uuid);

Available as @nightnetwork/obscura on npm.

To build Obscura, bun is recommended, but you can also use npm or yarn if you prefer.

To test obscura, using the tests folder, bun is required.

Follow the installation steps for your machine to install Bun at their official website.

Once installed, restart your terminal.

Testing

This is very important! Make sure to follow all steps to properly test Obscura.

There are two ways to test Obscura: In a terminal/node environment, and a browser environment.

To test Obscura in a terminal/node environment, you may run the test.ts file in the tests folder using bun tests/test.ts --watch. Any changes made to the testing file will automatically be reflected in the terminal.

To test Obscura in a browser environment, the steps are extremely different.

[!IMPORTANT] This is assuming we have not published Obscura to npm yet, and are using the local version of Obscura. If you have published Obscura to npm, you can skip the first few steps and just install it via npm.

First, build Obscura by running bun run build in the root directory. Next, run npm pack to pack the Obscura library. After that, run cd tests/templates to change directory to our browser testing environement. Next, run bun i ../../nightnetwork-obscura-1.0.0.tgz to install the Obscura library locally. (If the file name is different, change it accordingly.) Then, in the tests/templates directory, run bun run build. Finally, run bun test_server.ts --watch to start the testing server to serve the web version.

I have not yet added a testing environment without a bundler and using Obscura as a .js file that you can link, but feel free to do that for me if you wish to test that out as well.

Package detail

@nightnetwork/obscura

readme