diff --git a/README.md b/README.md index 1161189..0265a9d 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,33 @@ -# Helper Colletion +# Auth Server Helper -A bunch of useful functions and constants +Authentication middleware for express ## Usage ```js -const {auth,crypto,util,encoding,http_consts} = require('@scode/helper-collection'); +const auth = require('@scode/auth-server-helper'); +const password_helper = require('@scode/password_helper'); -// auth is a express middleware that uses a knex database conenction to authorize users -const authentication = auth(knex); +const users = { + foo: { + id: 0 + password: await password_helper.hash('bar'), + salt: '123' + } +} // add cookieParser to allow session management via cookies app.use(cookieParser()); -app.use(authentication.handler); + +// the middleware needs a function to determine user data +// this function can also return a promise +app.use(auth((user_name) => { + if (!users[user_name]) + return null; + return users[user_name]; +})); ``` -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 +when a client logs in, it will set a header called 'session' that the client can use to authorize the following requests. +it also sets a cookie to make requesting from the client more simple. (cookie parser is needed to make authentication with cookies possible)