balena-auth
v6.0.1
Published
Balena session authentication utilities
Downloads
47,051
Maintainers
Readme
balena-auth
Balena session authentication utilities
Role
The intention of this module is to provide low level access to how a balena authentication tokens are parsed and persisted.
THIS MODULE IS LOW LEVEL AND IS NOT MEANT TO BE USED BY END USERS DIRECTLY.
Unless you know what you're doing, use the balena SDK instead.
Installation
Install balena-auth
by running:
$ npm install --save balena-auth
Documentation
The module returns a class that you use to get an instance of the auth module.
It accepts the following params:
| Param | Type | Description |
| --- | --- | --- |
| options | Object | options |
| [options.dataDirectory] | string | false | the directory to use for storage in Node.js or false to create an isolated in memory instance. Values other than false are ignored in the browser. |
| [options.tokenKey] | string | the key used to store the last token in the storage. token
by default. |
Example
import BalenaAuth from 'balena-auth';
const auth = new BalenaAuth({
dataDirectory: '/opt/cache/balena',
tokenKey: 'token'
});
- auth
- ~setKey(key) ⇒ [ 'Promise' ].<void>
- ~hasKey() ⇒ [ 'Promise' ].<Boolean>
- ~removeKey() ⇒ Promise
- ~getType() ⇒ [ 'Promise' ].<TokenType>
- ~getKey() ⇒ [ 'Promise' ].<string>
- ~getAge() ⇒ [ 'Promise' ].<(number|undefined)>
- ~isExpired() ⇒ [ 'Promise' ].<boolean>
- ~isValid() ⇒ [ 'Promise' ].<boolean>
- ~get2FAStatus() ⇒ [ 'Promise' ].<('not_required'|'pending'|'passed')>
- ~needs2FA() ⇒ [ 'Promise' ].<boolean>
auth~setKey(key) ⇒ [ 'Promise' ].<void>
Kind: inner method of auth
Summary: Set the key
Access: public
| Param | Type | | --- | --- | | key | String |
Example
auth.setKey('...').then(() => { ... });
auth~hasKey() ⇒ [ 'Promise' ].<Boolean>
Kind: inner method of auth
Summary: Has a key
Returns: [ 'Promise' ].<Boolean> - has key
Access: public
Example
auth.hasKey().then((hasKey) => { ... });
auth~removeKey() ⇒ Promise
This promise is not rejected if there was no key at the time of removal.
Kind: inner method of auth
Summary: Remove the key
Access: public
Example
auth.removeKey();
auth~getType() ⇒ [ 'Promise' ].<TokenType>
Kind: inner method of auth
Summary: Gets the key type
Access: public
Example
auth.getType().then((type) => { ... });
auth~getKey() ⇒ [ 'Promise' ].<string>
Kind: inner method of auth
Summary: Gets the key
Access: public
Example
auth.getKey().then((key) => { ... });
auth~getAge() ⇒ [ 'Promise' ].<(number|undefined)>
Kind: inner method of auth
Summary: Gets the token age
Access: public
Example
auth.getAge().then((age) => { ... });
auth~isExpired() ⇒ [ 'Promise' ].<boolean>
Kind: inner method of auth
Summary: Checks if token is expired
Access: public
Example
auth.isExpired().then((expired) => { ... });
auth~isValid() ⇒ [ 'Promise' ].<boolean>
Kind: inner method of auth
Summary: Checks if token format is valid
Access: public
Example
auth.isValid().then((valid) => { ... });
auth~get2FAStatus() ⇒ [ 'Promise' ].<('not_required'|'pending'|'passed')>
Kind: inner method of auth
Summary: Gets whether passing a 2FA challenge is pending, passed or not required.
Access: public
Example
auth.get2FAStatus().then((get2FAStatus) => { ... });
auth~needs2FA() ⇒ [ 'Promise' ].<boolean>
Kind: inner method of auth
Summary: Checks whether passing 2FA is pending/needed
Access: public
Example
auth.needs2FA().then((needs2FA) => { ... });
Support
If you're having any problem, please raise an issue on GitHub and the balena team will be happy to help.
Tests
Run the test suite by doing:
$ npm test
Contribute
- Issue Tracker: github.com/balena-io-modules/balena-auth/issues
- Source Code: github.com/balena-io-modules/balena-auth
Before submitting a PR, please make sure that you include tests, and that tslint runs without any warning:
$ npm run lint
License
The project is licensed under the Apache 2.0 license.