DID Authentication

didauth is a JavaScript NPM libray for building DID authentication. Library uses JSDoc and Typescript typings for your convinience.

Example Demo Website

DID Authentication didauth.meet-martin.com

Demo Website Github Repository

Get Started

Installation

To use with Node.js:

$ npm install --save didauth

MATTR Platform Dependency

To use the library, you will need to have an account at MATTR, which provides all the necessary plumbing to support decentralized identifiers and a digital wallet.

Authentication

authentication is a pure function that creates an authentication request URL for DID Authentication with your MATTR tenant. The resulting URL is intended to be used to redirect the user.

As a result, MATTR platform calls supplied callback URL with the result that connects to your request by a supplied Challenge ID.

We return a monad @7urtle/lambda.AsyncEffect as the output of the function: https://www.7urtle.com/documentation-7urtle-lambda#lambda-AsyncEffect. On success the monad will hold a string with a redirect URL with JWS intended for the digital wallet. On failure it with hold a string describing the error.

import { authentication } from 'didauth';

const payload = {
    clientId: 'client id', // client id provided by MATTR
    clientSecret: 'client secret', // client secret provided by MATTR
    tenant: 'your-tenant.vii.mattr.global', // your tenant provided by MATTR
    did: 'did:method:code', // your verifier DID representing your application created in MATTR platform
    challengeId: 'your-challenge-id', // custom ID provided by your application to connect request internally
    templateId: 'presentation template id', // presentation template ID created in MATTR platform
    callbackURL: 'https://your-domain.tld/didauth/callback' // callback url of your website that the digital wallet will call
};

authentication(payload)
.trigger
(errors => console.log(errors) || ({
    statusCode: 500,
    body: 'Internal Server Error'
}))
(JWSURL => ({
    statusCode: 301,
    headers: {
        locations: JWSURL
    }
}));

Push Authentication

pushAuthentication is a pure function that creates an authentication digital wallet push request for DID Authentication with your MATTR tenant. It uses the recipientDID stored in your system to find the user's digital wallet and ask them for authentication through a push request on their phone.

As a result, MATTR platform calls supplied callback URL with the result that connects to your request by a supplied Challenge ID.

We return a monad @7urtle/lambda.AsyncEffect as the output of the function: https://www.7urtle.com/documentation-7urtle-lambda#lambda-AsyncEffect. On success the monad will hold the string 'Success' indicating that the authentication request was sent to a digital wallet. On failure it with hold a string describing the error.

import { pushAuthentication } from 'didauth';

const payload = {
    clientId: 'client id', // client id provided by MATTR
    clientSecret: 'client secret', // client secret provided by MATTR
    tenant: 'your-tenant.vii.mattr.global', // your tenant provided by MATTR
    did: 'did:method:code', // your verifier DID representing your application created in MATTR platform
    recipientDid: 'did:method:code', // users DID store by your application
    challengeId: 'your-challenge-id', // custom ID provided by your application to connect request internally
    templateId: 'presentation template id', // presentation template ID created in MATTR platform
    callbackURL: 'https://your-domain.tld/didauth/callback' // callback url of your website that the digital wallet will call
};

pushAuthentication(payload)
.trigger
(errors => console.log(errors) || ({
    statusCode: 500,
    body: 'Internal Server Error'
}))
(() => ({
    statusCode: 204
}));

Run Tests

The library has 100 % test coverage with unit tests and integration tests.

To run unit tests locally, call:

npm run unit-test

To run integration tests locally as well you will need .env file setup connected to your website and using your MATTR credentials. Please either reach out directly to MATTR to obtain them or open an issue in this repository to get help.

npm test

How Is The Library Built

didauth is built using functional programming principles on top of 7urtle/lambda. The library internally uses functional monads and therefor the output of the function calls are monads as well.

The library itself is written in pure JavaScript and uses Babel and Webpack to build. However, for your convinience Typescript typings and JSDoc are provided with the library.

The node code is build using ESM with support for both import and require and optimized for three-shaking to reduce your package sizes.

Contributors

Made with contributors-img.

Changelog

1.2.0

Library type changed to module using ESM imports/exports. Still supports commonjs require through webpack/babel build.
Optimizations for tree-shakeability of the library for both ESM and CJS.
Declaring Node support from version 12.16 (current node is 17.4.0, LTS is 16.13.2, and AWS Lambda defaults to node 14).
These changes were heavily tested with different configurations. However, if you encounter any issues, please report them on GitHub.

MeetMartin/didauth