Shifty is a tiny zero-dependency secrets generator, built for the web using TypeScript.
+Shifty is a lightweight secrets generator designed for the web, crafted using TypeScript. It provides a straightforward way to generate secure secrets and passwords without any external dependencies.
+## Table of Contents + +- [Installation](#installation) +- [Code Architecture](#code-architecture) + - [Shifty Class](#shifty-class) + - [Methods](#methods) + - [Constructor](#constructor) +- [Usage](#usage) +- [Why use Shifty](#why-use-shifty) +- [Options](#options) + - [Shifty](#shifty) + - [Shifty.generate](#shiftygenerate) +- [How it Works](#how-it-works) +- [Examples](#examples) + - [Basic Usage](#basic-usage) + - [Customizing Length and Hardening](#customizing-length-and-hardening) + - [Fallback Mechanism](#fallback-mechanism) + - [Integrating with Node.js (Using built-in crypto module)](#integrating-with-nodejs-using-built-in-crypto-module) + - [TypeScript Support](#typescript-support) + ## Installation ```sh yarn add @deepsource/shifty ``` +## Code Architecture + +#### Shifty Class + +- `hardenPassword: boolean` + +- `randomBuffer: Uint8Array` + +- `defaultLength: number` + +- `mode: "W3C" | "MS" | "Failover"` + +#### Constructor + +```Javascript +constructor(harden = true, defaultLength = DEFAULT_LENGTH) +``` + +- `harden`: This flag enables hardening the password using special characters. + +- `defaultLength`: The default length of the secret string in case no value is passed to generate. + +#### Methods +- `_validateCharacter(char: string): boolean` +Ensures the given character belongs to a valid character set. + +- `char`: The character to validate. +generate(length?: number): string +Generates a secret string. + +- `length`: (Optional) Length of the secret to be generated. If not provided, uses the default length. + +- `populateBuffer(): void` +Populates the buffer using web crypto or failover. + +- `_useCryptoRandomBuffer(): Uint8Array` +Generates a Uint8Array using the Web Crypto API. + +- `_useFailoverRandomBuffer(): Uint8Array` +Generates a Uint8Array using the failover method. Note: This is not cryptographically safe. + ## Usage > Shifty is built for the browser and won't work with Node. You can use the built-in [crypto](https://nodejs.org/api/crypto.html#crypto) module instead. @@ -31,7 +92,19 @@ const shifty = new Shifty((harden = true), (defaultLength = 16)); shifty.generate((length = 12)); // G8qZt7PEha^s ``` -### Options +## Why Use Shifty + +- **Zero Dependencies**: Shifty is a lightweight generator designed for the web with no external dependencies. This means you can integrate it seamlessly into your projects without worrying about additional dependencies. + +- **Built for Web Environments**: Shifty is optimized for the browser, providing a straightforward way to generate secure secrets and passwords in web applications. Its compatibility with the Web Crypto API ensures efficient cryptographic operations. + +- **Fallback Mechanism for Compatibility**: Even if the browser lacks support for the Web Crypto API, Shifty gracefully handles the situation by employing a fallback mechanism. This ensures that you can still generate passwords, albeit without cryptographic security. + +- **Customizable Length and Hardening**: With Shifty, you have control over the length of the generated secrets. Additionally, the `harden` option allows you to include special characters for added complexity and security. + +- **TypeScript Support**: Shifty is built using TypeScript, which means you can enjoy the benefits of static typing and improved code maintainability while using this library in your projects. + +## Options ##### `Shifty` @@ -65,3 +138,49 @@ The algorithm for generating the password is quite simple 3. If the character code is valid, append it to the secret string from step 3 4. If the character limit is satisfied, break. Else, regenerate the seed array from step 2 5. Return the generated string + +## Examples + +#### Basic Usage + +```javascript +import Shifty from "@deepsource/shifty"; + +const shifty = new Shifty(true, 16); +const generatedSecret = shifty.generate(12); // Example output: G8qZt7PEha^s +``` + +#### Customizing Length and Hardening + +```javascript +const shifty = new Shifty(true, 20); // Set default length to 20 +const hardenedSecret = shifty.generate(12); // Example output: G8qZt7PEha^s$#tR6&9 +``` + +#### Fallback Mechanism + +```javascript +const shifty = new Shifty(true, 16); +const generatedSecret = shifty.generate(12); // Example output (fallback): G8qZt7PEha^s +``` + +#### Integrating with Node.js (Using built-in crypto module) + +```javascript +import { randomBytes } from 'crypto'; + +function generateRandomString(length) { + return randomBytes(Math.ceil(length / 2)).toString('hex').slice(0, length); +} + +const generatedSecret = generateRandomString(12); // Example output: 3a2fG7c1e8b9 +``` + +#### Typescript Support + +```javascript +import Shifty from "@deepsource/shifty"; + +const shifty = new Shifty(true, 16); +const generatedSecret: string = shifty.generate(12); // Example output: G8qZt7PEha^s +```