@selfkey/node-lib
Selfkey sdk for third party integrations written in Node.js
Contents
Install
Requires Node version 10 or abow
npm install --save @selfkey/node-lib
Usage
const sk = require('@selfkey/node-lib');
or ES6 syntax
import sk from '@selfkey/node-lib';
API
Modules
- auth/generate-access-token
- auth/generate-challenge-token
- auth/generate-nonce
- auth/validate-access-token
- auth/validate-challenge-token
- auth/verify-challenge-signature
- did/parse
- did/resolver
- identity/attribute-manager
- identity/repository
- identity/utils
- jwt/constants
- jwt/issue
- jwt/parse
- jwt/validate
- key/hmac
- key/rsa
- key/validate-private-key
- kycc/get-user-data-for-token
auth/generate-access-token
auth/generate-access-token~generateAccessToken(did, algorithm, secret, [expiresIn])
⇒ Promise.<string>
Generate access token
Kind: inner method of auth/generate-access-token
Returns: Promise.<string>
- jwtToken
Param | Type | Default |
---|
did | string | |
algorithm | string | |
secret | string | |
[expiresIn] | string | "'1h'" |
Example
await sk.auth.generateAccessToken(did, 'rsa', 'secret')
auth/generate-challenge-token
auth/generate-challenge-token~generateChallengeToken(did, algorithm, secret, [expiresIn])
⇒ Promise.<string>
Generate challenge token
Kind: inner method of auth/generate-challenge-token
Returns: Promise.<string>
- jwtToken
Param | Type | Default |
---|
did | string | |
algorithm | string | |
secret | string | |
[expiresIn] | string | "'30m'" |
Example
await sk.auth.generateChallengeToken(did, 'rsa', 'secret')
auth/generate-nonce
auth/generate-nonce~generateNonce([length])
⇒ Promise.<string>
Generates base64 encoded random string
Kind: inner method of auth/generate-nonce
Returns: Promise.<string>
- nonce
Param | Type | Default |
---|
[length] | number | 64 |
Example
await sk.auth.generateNonce();
auth/validate-access-token
auth/validate-access-token~validateAccessToken(token, algorithm, key)
⇒ Promise.<object>
Validates access token
Kind: inner method of auth/validate-access-token
Returns: Promise.<object>
- decodedToken
Throws:
- If token is invalid
- if subject is not did
- if token type is not access
Param | Type |
---|
token | string |
algorithm | string |
key | string | Buffer |
Example
await sk.auth.validateAccessToken(token, 'hmac', 'secret');
auth/validate-challenge-token
auth/validate-challenge-token~validateChallengeToken(token, algorithm, key)
⇒ Promise.<object>
Validates challenge token
Kind: inner method of auth/validate-challenge-token
Returns: Promise.<object>
- decodedToken
Throws:
- If token is invalid
- if subject is not did
- if token type is not challenge
Param | Type |
---|
token | string |
algorithm | string |
key | string | Buffer |
Example
await sk.auth.validateChallengeToken(token, 'hmac', 'secret');
auth/verify-challenge-signature
auth/verify-challenge-signature~verifyChallengeSignature(nonce, signature, did)
⇒ Promise.<boolean>
Validates challenge Signature
Kind: inner method of auth/verify-challenge-signature
Returns: Promise.<boolean>
- is valid signature
Throws:
- key not found in resolved did document
- if no registered verifier for that key type
Param | Type |
---|
nonce | string |
signature | object |
did | string |
Example
await sk.auth.verifyChallengeSignature(nonce, signature, did);
did/parse
did/parse~parse(did)
⇒ object
Parses did string to components
Kind: inner method of did/parse
Returns: object
- parsedDid
Throws:
- if invalid did is provided
Example
sk.did.parse('did:selfkey:0xdsdasddasdsa...');
did/resolver
did/resolver~resolvers
: object
Kind: inner constant of did/resolver
Properties
Name | Type | Description |
---|
eth | object | eth did resolver |
sekfkey | object | selfkey did resolver |
did/resolver~isSupported(did)
⇒ boolean
Checks if a resolver exists for that particular did
Kind: inner method of did/resolver
Returns: boolean
- isSuppored
Example
sk.did.isSupported('did:selfkey:0xdsdasddasdsa...');
sk.did.isSupported('did:eth:0xdsdasddasdsa...');
sk.did.isSupported('did:unknown:0xdsdasddasdsa...');
did/resolver~resolve(did)
⇒ object
Resolves did document
Kind: inner method of did/resolver
Returns: object
- didDocument
Example
await sk.did.resolve('did:selfkey:0xdsdasddasdsa...');
did/resolver~registerMethodResolver(method, resolver)
Register custom resolver for a did method
Kind: inner method of did/resolver
Param | Type |
---|
method | string |
resolver | object |
Example
sk.did.register('new-method', resolver);
identity/attribute-manager
identity/attribute-manager.AttributeManager
Kind: static class of identity/attribute-manager
new exports.AttributeManager()
Creates an instance of AttributeManager.
attributeManager.addRepository(repository)
Adds a new repository
Kind: instance method of AttributeManager
Param | Type |
---|
repository | identity.Repository |
attributeManager.removeRepository(repository)
Remove a repository
Kind: instance method of AttributeManager
Param | Type |
---|
repository | identity.Repository |
attributeManager.findRepositoryForAttribute(attr)
⇒ identity.Repository
| null
Finds a repository for a given attribute
Kind: instance method of AttributeManager
Param | Type |
---|
attr | object | string |
attributeManager.zipAttributesWithRequirements(attributes, [requirements])
⇒ Array
Given an array of attributes and requirements, tries to much between them
Kind: instance method of AttributeManager
Param | Type | Default |
---|
attributes | Array | |
[requirements] | Array | [] |
attributeManager.validateOneAttribute(attr, requirement)
⇒ object
Given an attribute and requirement validates the attribute
Kind: instance method of AttributeManager
Param | Type |
---|
attr | object |
requirement | object |
attributeManager.validateAttributes(attributes, requirements)
⇒ object
Given a list of attribute and requirements, validates all attributes
Kind: instance method of AttributeManager
Param | Type |
---|
attributes | Array |
requirements | Array |
AttributeManager.createWithSelfkeyRepository(options)
⇒ AttributeManager
Creates an AttributeManager and initializes it with selfkey repository
Kind: static method of AttributeManager
identity/attribute-manager~AttributeManager
Attribute Manager, manages multiple repositories of attributes
Kind: inner class of identity/attribute-manager
identity/repository
identity/repository.Repository
Kind: static class of identity/repository
new exports.Repository([config])
Creates an instance of Repository.
Param | Type | Default |
---|
[config] | object | {} |
repository.resolveAll()
Resolve all repository data
Kind: instance method of Repository
repository.resolveJsonSchema(schema, [config])
⇒ object
Resolve one JSON schema
Kind: instance method of Repository
Param | Type | Default |
---|
schema | object | string | |
[config] | object | {} |
repository.resolveUiSchema(schema, [config])
⇒ object
Resolve one ui schema
Kind: instance method of Repository
Param | Type | Default |
---|
schema | object | string | |
[config] | object | {} |
repository.getValidator()
⇒
Creates an Ajv validator for the repository data
Kind: instance method of Repository
Returns: Ajv instance
repository.validateData(schemaId, data)
⇒ object
Given schemaId and data, validates the data based on relevant schema
Kind: instance method of Repository
Returns: object
- {valid:boolean, errors: array}
Param | Type |
---|
schemaId | string |
data | object |
Repository.createSelfkeyRepo([options])
⇒ Repository
Creates a repository initialized with selfkey data
Kind: static method of Repository
Param | Type | Default |
---|
[options] | object | {} |
Repository.fromConfig(config, [ui])
⇒ Repository
Creates and preloads a Repository from a config object
Kind: static method of Repository
Param | Type | Default |
---|
config | object | |
[ui] | boolean | false |
Repository.fromSchemaId(schemaId, [ui])
⇒ Repository
Creates and preloads a Repository based on attribute schema id
Kind: static method of Repository
Param | Type | Default |
---|
schemaId | string | |
[ui] | boolean | false |
identity/repository~Repository
Repository Class allows to load identity attribute repository and validate schemas
Part of identity
namespace
Kind: inner class of identity/repository
identity/utils
- identity/utils
~attributeMapBySchema(attributes)
⇒ object
~resolveAttributeFiles(all, fileProcessor)
⇒ object
~denormalizeDocumentsSchema(typeSchema, value, documents, maxDepth)
⇒ object
~normalizeDocumentsSchema(typeSchema, value, documents, maxDepth)
⇒ object
~schemaContainsFile(schema, maxDepth)
⇒ boolean
~fetchJson(url, options)
⇒ Promise.<object>
~dereferenceSchema(schema, options)
⇒ Promise.<object>
identity/utils~attributeMapBySchema(attributes)
⇒ object
Map list of attributes to schema name
Kind: inner method of identity/utils
Returns: object
- an object with attribute name as keys
Param | Type | Description |
---|
attributes | Array | array of identity attributes |
identity/utils~resolveAttributeFiles(all, fileProcessor)
⇒ object
Given a attribute data object and a file processor, process all files in the data object
Kind: inner method of identity/utils
Returns: object
- a new attribute data object with processed files
Param | Type | Description |
---|
all | data | or part of the attribute data object |
fileProcessor | function | |
identity/utils~denormalizeDocumentsSchema(typeSchema, value, documents, maxDepth)
⇒ object
Given a attribute data object and an array of documents, insert the documents
into the data object where they are referenced from
Kind: inner method of identity/utils
Param | Type | Description |
---|
typeSchema | object | a json schema object |
value | object | an attribute data object |
documents | array | an array of documents |
maxDepth | integer | max search depth in attribute data object |
identity/utils~normalizeDocumentsSchema(typeSchema, value, documents, maxDepth)
⇒ object
Given a attribute data object
export all documents from the object to a separate array, leaving documnent
references behind
Kind: inner method of identity/utils
Param | Type | Description |
---|
typeSchema | object | a json schema object |
value | object | an attribute data object |
documents | array | an array of documents |
maxDepth | integer | max search depth in attribute data object |
identity/utils~schemaContainsFile(schema, maxDepth)
⇒ boolean
Check if schema contains a file
Kind: inner method of identity/utils
Param | Type | Description |
---|
schema | object | json schema object |
maxDepth | integer | maximum depth to search for in the object tree |
identity/utils~fetchJson(url, options)
⇒ Promise.<object>
Fetch json from remote server.
Optionally specify max number of attempts to do on failure (3 by default)
Kind: inner method of identity/utils
Returns: Promise.<object>
- json loaded from server
Param | Type |
---|
url | string |
options | object |
Example
async sk.identity.utils.fetchJson('http://platform.selfkey.org/schema/attribute/first-name.json', {maxAttempts: 10});
identity/utils~dereferenceSchema(schema, options)
⇒ Promise.<object>
Given a scheme object, load all references from the schema
And combine into one json schema object
Kind: inner method of identity/utils
Returns: Promise.<object>
- dereferences json schema object
Param | Type |
---|
schema | object |
options | object |
jwt/constants
jwt/issue
jwt/issue~issueJWT(subject, requestedAlgorithm, secret, [expiresIn], additionalClaims)
⇒ Promise.<string>
Issue a new JWT token
Kind: inner method of jwt/issue
Returns: Promise.<string>
- jwt
Throws:
- if unknown algorithm provided
- if secret deemed as not secure enough
Param | Type | Default | Description |
---|
subject | string | | sub claim |
requestedAlgorithm | string | | signature algorithm |
secret | string | Buffer | | secret key for signature |
[expiresIn] | string | "1h" | longevity of the token |
additionalClaims | object | | claims to include in the token |
Example
sk.jwt.issueJWT('simple-session', 'hmac', 'test');
jwt/parse
jwt/parse~parseJWT(token)
⇒ object
Parse a JWT token
Kind: inner method of jwt/parse
Returns: object
- decodedJwt
Param | Type | Description |
---|
token | string | jwt token |
Example
sk.jwt.parseJWT(token);
jwt/validate
jwt/validate~validateJWT(token, requestedAlgorithm, key)
⇒ Promise.<(object|null)>
Validate a JWT token
Kind: inner method of jwt/validate
Returns: Promise.<(object|null)>
- decodedJwt
Throws:
- if unknown algorithm provided
Param | Type | Description |
---|
token | string | jwt token |
requestedAlgorithm | string | algorithm name |
key | string | the key to validate the token against |
Example
sk.jwt.validateJWT(token, 'hmac', key);
key/hmac
key/hmac~generateHMACKey([length], [encoding])
⇒ Promise.<(string|Buffer)>
Generate a HMAC Key
Kind: inner method of key/hmac
Returns: Promise.<(string|Buffer)>
- key
Param | Type | Default | Description |
---|
[length] | number | 64 | key length in bytes |
[encoding] | string | "base64" | the output encoding of the key |
Example
sk.key.generateHMACKey();
key/hmac~generateHMACKey(secret, [encoding])
⇒
Calculate the bytes length of secret key
Kind: inner method of key/hmac
Returns: number
Param | Type | Default | Description |
---|
secret | string | | |
[encoding] | string | "base64" | the input encoding of the secret |
Example
sk.key.getSecretLength(secret);
key/rsa
key/rsa~generateRSAKeyPair([length])
⇒ Promise.<object>
Generate a RSA Key Pair
Kind: inner method of key/rsa
Returns: Promise.<object>
- keypair - contains publicKey adn privateKey
Param | Type | Default | Description |
---|
[length] | number | 4096 | key length in bytes |
Example
sk.key.generateRSAKeyPair();
key/validate-private-key
key/validate-private-key~checkSecretLength(key, algorithm)
⇒ boolean
Checks if secret length is good enough
Kind: inner method of key/validate-private-key
Returns: boolean
- - isKeyLongEnough
Param | Type |
---|
key | string |
algorithm | string |
Example
sk.key.checkSecretLength();
kycc/get-user-data-for-token
kycc/get-user-data-for-token~getUserDataForToken(token, options)
⇒ Promise.<KYCCUserObject>
Fetch user data via token
Kind: inner method of kycc/get-user-data-for-token
Returns: Promise.<KYCCUserObject>
- user object
Throws:
- if no instanceUrl in options
- if no templateId in options
- if invalid token
- if invalid user for token
Param | Type | Description |
---|
token | string | jwt token |
options | GetUserDataForTokenOptions | |
Example
async sk.kycc.getUserDataForToken(token, options);
kycc/get-user-data-for-token~FileProcessor
File Processor
Kind: inner typedef of kycc/get-user-data-for-token
Properties
Name | Type |
---|
stream | boolean |
process | function |
Example
{ stream: false, process: (file, id) => file }
kycc/get-user-data-for-token~GetUserDataForTokenOptions
Options used in getUserDataForToken function
Kind: inner typedef of kycc/get-user-data-for-token
Properties
Name | Type |
---|
instanceUrl | string |
templateId | string |
fileProcessor | FileProcessor |
kycc/get-user-data-for-token~KYCCUserObject
User Object
Kind: inner typedef of kycc/get-user-data-for-token
Properties
Name | Type | Description |
---|
id | string | id of user in KYCC |
attributes | object | map from attribute id to attribute value |
Example
{
id: '5ddd5b1656fbcef0dd389637',
attributes: {
firstName: {
id: '5d076f0a315423134405cbc4',
label: 'First Name',
required: true,
schema: 'http://platform.selfkey.org/schema/attribute/first-name.json',
valid: true,
value: 'first-name'
},
lastName: {
label: 'Last Name',
id: '5d076f20315423f5db05cbc6',
required: true,
schema: 'http://platform.selfkey.org/schema/attribute/last-name.json',
valid: true,
value: 'last-name'
},
email: {
id: '5d13577f72089544cb86cda7',
label: 'Email Address',
required: true,
schema: 'http://platform.selfkey.org/schema/attribute/email.json',
valid: true,
value: 'test-4952@test.com'
},
}
Examples
License
The GPL-3.0 License
Copyright (c) 2018 SelfKey Foundation https://selfkey.org/