unixcrypt-browser/README.md

Node.js implementation of Unixcrypt, specifically SHA-256 and SHA-512

# Unixcrypt for Browser

[![node.js build](https://github.com/sharevb/unixcrypt-browser/actions/workflows/master.yaml/badge.svg)](https://github.com/sharevb/unixcrypt-browser/actions/workflows/master.yaml)
[![coverage](https://sharevb.github.io/unixcrypt-browser/badges/coverage-2.0.0.svg)](https://github.com/sharevb/unixcrypt-browser/actions)
[![version](https://img.shields.io/npm/v/unixcrypt-browser.svg)](https://codecov.io/github/sharevb/unixcrypt-browser)
[![license](https://img.shields.io/github/license/sharevb/unixcrypt-browser.svg)](https://www.apache.org/licenses/LICENSE-2.0)

A Browser module for encrypting and verifying passwords according to the SHA-256 and SHA-512 Crypt standard:
https://www.akkadia.org/drepper/SHA-crypt.txt

## Installation

```sh
$ npm install unixcrypt-browser
```

## Usage

### JavaScript

The JavaScript usage should be identical to the TypeScript below.

### TypeScript

```typescript
import { encrypt, verify } from "unixcrypt-browser"

const plaintextPassword = "password"

// without providing salt, random salt is used, and default number of rounds
const pwHash = encrypt(plaintextPassword)

// verify password with generated hash
console.log(verify(plaintextPassword, pwHash))
// true

// specify number of rounds
const moreRounds = encrypt(plaintextPassword, "$6$rounds=10000")
console.log(verify(plaintextPassword, moreRounds))
// true

// provide custom salt
const customSalt = encrypt(plaintextPassword, "$6$salt")
console.log(verify(plaintextPassword, customSalt))
// true

// or provide both rounds and salt
const customRoundsAndSalt = encrypt(plaintextPassword, "$6$rounds=10000$salt")
console.log(verify(plaintextPassword, customRoundsAndSalt))
// true

// you can also use SHA-256
const sha256 = encrypt(plaintextPassword, "$5")
console.log(verify(plaintextPassword, sha256))
// true
```

## Test

The tests are written with the built-in [node:assert](https://nodejs.org/api/assert.html) module, using the [vitest](https://vitest.dev/) test runner.

```sh
$ npm test
```

or

```sh
$ npm run test:watch
```

to get automatic re-tests when files are changed.