nomo-auth v1.1.2

Nomo-Auth

nomo-auth is a protocol for authenticating WebOns, based on cryptographic signatures. With nomo-auth, WebOns can authenticate without any passwords or even without any user interaction at all.

At its core, nomo-auth injects a few headers into HTTP-requests sent by a Nomo WebOn.

Protocol Specification

See the browser implementation of the Nomo-Auth protocol. This implementation serves as a specification of Nomo-Auth. Nomo-Auth is a simple protocol, so the whole implementation is only a small amount of TypeScript-code.

How to use

In the frontend, we recommend using one of the following functions from the nomo-webon-kit:

• nomoAuthHttp: Nomo-Auth via native code
• nomoAuthFetch: Nomo-Auth via JavaScript-fetch

Those functions inject the needed HTTP-headers automatically and retry requests upon 403-errors (according to the specification above).

If this specific 403-flow does not fit your needs, you could roll a customized flow based on the function nomoSignAuthMessage.

In the backend, we recommend learning how to verify signatures (see the sections below).

Signature Verification

nomo-auth offers two different types of address/signature-pairs: nomo-auth-addr + nomo-sig as well as nomo-eth-addr + nomo-eth-sig. To secure a backend, at least one of those address/signature-pairs must be verified.

nomo-auth-addr + nomo-sig

nomo-auth-addr is a special address that is derived from the user's wallet and the target-domain of the HTTP-request.

nomo-sig is an “Eurocoin-message-signature" that can be verified with packages like bitcoinjs-message. See the function verifyNomoSignature as an example for verifying a nomo-sig.

:warning: nomo-auth-addr will change whenever the target-domain of your HTTP-requests changes! If you rely on nomo-auth-addr in a database, then you must never ever change the domain of your backend.

nomo-eth-addr + nomo-eth-sig

nomo-eth-addr is the regular Ethereum/Smartchain-address of a Nomo user.

nomo-eth-sig is an "Ethereum-message-signature" that can be verified with packages like ethers.js or web3.js. See the ethSigDemo as an example for verifying a nomo-eth-sig.

npm package

The nomo-auth npm package is an express.js-middleware for Nomo-Auth. Nevertheless, even if you do not use express.js, Nomo-Auth is simple enough to be integrated without any middleware with just a few lines of code.

Installation

To use nomo-auth with express.js, you can install it via npm:

npm install nomo-auth

Usage

Here's an example of how to add the nomo-auth middleware to your Express application:

import express from 'express';
import { nomoMiddleware } from 'nomo-auth';

const app = express();

const config = {
  nomo_token_secret: 'Your JWT token secret',
  nomo_token_validity: 'Token validity in seconds', // default 3h
  auth_addr_validation_disabled: 'true or false', // default false
  webon_name_list: ['Your webon name'],
  min_webon_version: '1.0.1' // Optional
};

app.use(nomoMiddleware(config));

In this example, you import the nomoMiddleware function and add it as middleware to your Express app. Replace the configuration values with the appropriate settings for your application.

Nomo Headers

To retrieve these NOMO Headers, you can use the getNomoHeaderData function. This function takes an Express Request object as its parameter and returns an object containing the extracted NOMO Headers. Here's how to use it:

import { getNomoHeaderData } from 'nomo-auth';

app.get('/your-endpoint', (req, res) => {
  const nomo_headers = getNomoHeaderData(req);

  // You can now access and use the NOMO headers in your application
  console.log(nomo_headers.nomo_token);
  console.log(nomo_headers.nomo_sig);
  // ...
  // Handle requests based on NOMO headers
});

If you need more information regarding Nomo Headers, please refer to the Nomo Auth browser implementation.