114 lines
3.4 KiB
Markdown
114 lines
3.4 KiB
Markdown
# 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
|