# Helper Colletion

A bunch of useful functions and constants

## Usage

```js
const {auth,crypto,util,encoding,http_consts} = require('@scode/helper-collection');

// auth is a express middleware that uses a knex database conenction to authorize users
const authentication = auth(knex);

// add cookieParser to allow session management via cookies
app.use(cookieParser());
app.use(authentication.handler);

```

to create the necessary users table, add the following to your migrations

```js
function up(knex) {
  await knex.schema.createTable ('users', (table) => {
    table.increments ('id');
    table.string ('name');
    table.string ('email');
    table.string ('password');
    table.string ('salt');
    table.boolean ('deleted')
      .default (false);
  });
}
```

```js

// additionally it offers functions like create_user
const salt = crypto.create_salt();
const hash = crypto.hash_sha512('1234', salt);
authentication.create_user('test', 'test@example.com', hash, salt);

// helper functions include a bunch of different quick functions

// util
const json = util.try_parse_json('}!!invalid json') // returns null instead of throwing an error
const n = util.truncate_decimal(23.45678, 2); // n = 23.45

// crypto
const rand_hex = crypto.random_hex(16); // outputs 16 byte random hex
const rand_salt = crypto.create_salt(); // same as random_hex, but with fixed length of 32 bytes
const random_string = crypto.random_string(16) // output 16 character long random string
const hash = crypto.hash_sha512(random_string, random_hex); // returns sha 512 hex
const check = crypto.checksum('foo'); // returns a sha 256 hex
const argon = crypto.argon_hash(random_string); // returns an argon hash
const is_argon_valid = crypto.argon_verify(argon, random_hex); // returns false because a different input was used

// encoding
const hex = encoding.to_hex('abc'); // convert any encoding to hex, default is utf-8
const b64 = encoding.to_b64(hex, 'hex'); // convert any encoding to base64, default is utf-8
const utf8 = encoding.to_utf8(hex, 'hex'); // convert any encoding to utf-8, no default

// jwt like object signing
const signed = crypto.sign_object({foo: 'bar'}, 'secret');
const dec = crypto.decode_signed(signed); // decode a signed object without verifying the signature
const ver = crypto.verify_signature(signed, 'secret', 10000); // verifies the signature and returns the contents. the timeout is in milliseconds and optional, timing will be ignored if omitted.

// http consts contain useful constants like response codes

http_consts.status_ok // easier to understand than '200'
```

## Breaking Changes

### v2.0

- functions.random_string is now synchronous
- functions.random_hex
  - is now synchronous
  - uses length for the actual string length instead of the contained bytes
- functions.create_salt is now synchronous

### v3.0

- functions.hash has been removed
  - replaced by hash_sha512 (different hash algorithm)
- all functions are now only accessible via their module
- new module structure:
  - crypto:
    - checksum
    - create_salt
    - decode_signed
    - get_signature_info
    - hash_sha512
    - random_hex
    - random_string
    - sign_object
    - verify_signature
  - util
    - try_parse_json
    - truncate_decimal
  - encoding
    - to_b64
    - to_hex
    - to_utf8
  - auth {...}
  - http_consts {...}

## Deprecations

### v2.4

- functions.hash has been deprecated since it was using pbkdf2
  - replaced by hash_sha512