@arcblock/jwt 1.6.10

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2018-2019 ArcBlock
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,148 @@
+![did-auth](https://www.arcblock.io/.netlify/functions/badge/?text=did-auth)
+
+[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![docs](https://img.shields.io/badge/powered%20by-arcblock-green.svg)](https://docs.arcblock.io)
+[![Gitter](https://badges.gitter.im/ArcBlock/community.svg)](https://gitter.im/ArcBlock/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
+
+This library aims to ease the process of handling `Did-Auth` process between different parts, its implemented according to [ABT-DID-Protocol](https://github.com/ArcBlock/abt-did-spec), and can eliminate the threat of middle-man attach if properly used, there are typically 2 use case for the library:
+
+- `dApp <--> dApp`: for inter application communication, we provide `AppAuthenticator` and `AppHandlers`
+- `dApp <--> DID Wallet`: for application and wallet communication, we provide `WalletAuthenticator` and `WalletHandlers`
+
+## Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [Install](#install)
+- [Usage](#usage)
+  - [Between dApp and DID Wallet](#between-dapp-and-did-wallet)
+  - [Between dApp and dApp](#between-dapp-and-dapp)
+    - [Initialize authenticator and handlers](#initialize-authenticator-and-handlers)
+    - [For the server](#for-the-server)
+    - [For the client](#for-the-client)
+
+## Install
+
+```sh
+npm install @arcblock/jwt
+// or
+yarn add @arcblock/jwt
+```
+
+## Usage
+
+### Between dApp and DID Wallet
+
+`WalletAuthenticator` and `WalletHandlers` should be used together with [@ocap/react-forge](https://www.npmjs.com/package/@ocap/react-forge).
+
+```js
+const { fromRandom } = require('@ocap/wallet');
+const { WalletAuthenticator, WalletHandlers } = require('@arcblock/jwt');
+
+// First setup authenticator and handler factory
+const wallet = fromRandom().toJSON();
+const authenticator = new WalletAuthenticator({
+  wallet,
+  baseUrl: 'http://wangshijun.natapp1.cc',
+  appInfo: {
+    description: 'Starter projects to develop web application on forge',
+    icon: '/images/logo@2x.png',
+    name: 'Forge Web Starter',
+  },
+  chainInfo: {
+    host: 'http://did-workshop.arcblock.co:8210/api',
+    id: 'forge',
+  },
+});
+
+const handlers = new WalletHandlers({
+  authenticator,
+  tokenStorage: new MongoStorage({ url: process.env.MONGO_URI }),
+});
+
+// Then attach handler to express server
+const express = require('express');
+const app = express();
+
+// This is required if you want to use dynamic baseUrl inference
+app.set('trust proxy', true);
+
+handlers.attach({
+  prefix: '/api/did',
+  action: 'login',
+  claims: {
+    profile: () => ({
+      fields: ['fullName', 'email'],
+      description: 'Please provide your name and email to continue',
+    }),
+  },
+  onAuth: async ({ claims, userDid }) => {
+    try {
+      const profile = claims.find((x) => x.type === 'profile');
+      console.info('login.success', { userDid, profile });
+    } catch (err) {
+      console.error('login.error', err);
+    }
+  },
+});
+
+// Then your app will have 5 api endpoints that can be consumed by AuthComponent
+// - `GET /api/did/login/token` create new token
+// - `GET /api/did/login/status` check for token status
+// - `GET /api/did/login/timeout` expire a token
+// - `GET /api/did/login/auth` create auth response
+// - `POST /api/did/login/auth` process login request
+```
+
+### Between dApp and dApp
+
+Please note that `AppAuthenticator` and `AppHandlers` should be used to sign and verify the message sent between dApps, so there must are both a client and a server.
+
+#### Initialize authenticator and handlers
+
+```js
+const { fromRandom } = require('@ocap/wallet');
+const { AppAuthenticator, AppHandlers } = require('@arcblock/jwt');
+
+// First setup authenticator and handler factory
+const wallet = fromRandom().toJSON();
+const authenticator = new AppAuthenticator(wallet);
+const handlers = new AppHandlers(authenticator);
+```
+
+#### For the server
+
+```js
+const express = require('express');
+const app = express();
+
+app.post('/api/endpoint', handlers.attach(), (req, res) => {
+  console.log('client.appPk', req.appPk);
+  console.log('verified payload', req.payload);
+
+  // Sent signed response: sensitive info should not be here
+  res.jsonSecure({
+    key: 'value',
+  });
+});
+```
+
+#### For the client
+
+```js
+const axios = require('axios');
+
+const signedPayload = authenticator.sign({
+  amount,
+  depositorDid,
+  depositorPk,
+  withdrawer: appAuth.wallet.address,
+  merchantId: process.env.MERCHANT_ID,
+});
+
+const res = await axios.post('http://example.com/api/endpoint', signedPayload);
+const payload = await authenticator.verify(res.data);
+if (payload.error) {
+  throw new Error(payload.error);
+}
+// Do something with the payload
+```

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+// Generate by [js2dts@0.3.3](https://github.com/whxaxes/js2dts#readme)
+
+declare const _Lib: _Lib.T102;
+declare namespace _Lib {
+  export interface T101 {
+    tolerance?: number;
+    enforceTimestamp?: boolean;
+    signerKey?: string;
+  }
+  export interface T102 {
+    sign: (signer: string, sk: string, payload?: any, doSign?: boolean, version?: string) => string;
+    verify: (token: string, signerPk: string, T100?: _Lib.T101) => boolean;
+    decode: (token: string, payloadOnly?: boolean) => any;
+  }
+}
+export = _Lib;

package/lib/index.js

@@ -0,0 +1,206 @@
+const semver = require('semver');
+const stringify = require('json-stable-stringify');
+const Mcrypto = require('@ocap/mcrypto');
+const { toHex, toBase64, fromBase64 } = require('@ocap/util');
+const { toDid, toStrictHex, toTypeInfo, isValid, isFromPublicKey } = require('@arcblock/did');
+
+// eslint-disable-next-line
+const debug = require('debug')(require('../package.json').name);
+
+const { types, getSigner } = Mcrypto;
+
+// we start hashing before signing after 1.1
+const JWT_VERSION_REQUIRE_HASH_BEFORE_SIGN = '1.1.0';
+
+// since ios requires a fixed length of input to sign, we use sha3 here before sign
+const hasher = Mcrypto.Hasher.SHA3.hash256;
+
+/**
+ * Generate and sign a jwt token
+ *
+ * @public
+ * @static
+ * @param {string} signer - address string
+ * @param {string} sk - hex encoded secret key
+ * @param {object} [payload={}] - data to be included before signing
+ * @param {boolean} [doSign=true] - do we need to sign the payload or just return the content to be signed
+ * @returns {string} hex encoded signature
+ */
+const sign = (signer, sk, payload = {}, doSign = true, version = '1.0.0') => {
+  if (isValid(signer) === false) {
+    throw new Error('Cannot do sign with invalid signer');
+  }
+
+  const type = toTypeInfo(signer);
+  const headers = {
+    [types.KeyType.SECP256K1]: {
+      alg: 'ES256K',
+      type: 'JWT',
+    },
+    [types.KeyType.ED25519]: {
+      alg: 'Ed25519',
+      type: 'JWT',
+    },
+    [types.KeyType.ETHEREUM]: {
+      alg: 'Ethereum',
+      type: 'JWT',
+    },
+  };
+
+  // make header
+  const header = headers[type.pk];
+  const headerB64 = toBase64(stringify(header));
+
+  // make body
+  const now = Math.floor(Date.now() / 1000);
+  let body = {
+    iss: toDid(signer),
+    iat: String(now),
+    nbf: String(now),
+    exp: String(now + 5 * 60),
+    version,
+    ...(payload || {}),
+  };
+  // remove empty keys
+  body = Object.keys(body)
+    .filter((x) => {
+      if (typeof body[x] === 'undefined' || body[x] == null || body[x] === '') {
+        return false;
+      }
+
+      return true;
+    })
+    .reduce((acc, x) => {
+      acc[x] = body[x];
+      return acc;
+    }, {});
+
+  const bodyB64 = toBase64(stringify(body));
+  debug('sign.body', body);
+
+  // istanbul ignore if
+  if (!doSign) {
+    return `${headerB64}.${bodyB64}`;
+  }
+
+  // make signature
+  const msgHex = toHex(`${headerB64}.${bodyB64}`);
+  const msgHash = semver.gte(semver.coerce(version).version, JWT_VERSION_REQUIRE_HASH_BEFORE_SIGN)
+    ? hasher(msgHex)
+    : msgHex;
+  const sigHex = getSigner(type.pk).sign(msgHash, sk);
+  const sigB64 = toBase64(sigHex);
+
+  return [headerB64, bodyB64, sigB64].join('.');
+};
+
+/**
+ * Decode info from jwt token
+ *
+ * @public
+ * @static
+ * @param {string} token - jwt string
+ * @param {boolean} [payloadOnly=false]
+ * @returns {object}
+ */
+const decode = (token, payloadOnly = true) => {
+  const [headerB64, bodyB64, sigB64] = token.split('.');
+  const header = JSON.parse(fromBase64(headerB64));
+  const body = JSON.parse(fromBase64(bodyB64));
+  const sig = Buffer.from(fromBase64(sigB64)).toString('hex');
+  if (payloadOnly) {
+    return body;
+  }
+  return { header, body, signature: `0x${toStrictHex(sig)}` };
+};
+
+/**
+ * Verify a jwt token signed with signerPk and signerDid
+ *
+ * @public
+ * @static
+ * @param {string} token - the jwt token
+ * @param {string} signerPk - signer public key
+ * @param {object} options - options to customize the verify
+ * @param {number} [options.tolerance=5] - number of seconds to tolerant expire
+ * @param {boolean} [options.enforceTimestamp=true] - whether should be verify timestamps?
+ * @param {string} [options.signerKey='iss'] - which field should be used to pick the signer
+ * @returns {boolean}
+ */
+const verify = (token, signerPk, { tolerance = 5, enforceTimestamp = true, signerKey = 'iss' } = {}) => {
+  try {
+    const [headerB64, bodyB64] = token.split('.');
+    const { header, body, signature } = decode(token, false);
+    if (!signature) {
+      debug('verify.error.emptySig');
+      return false;
+    }
+    if (!header.alg) {
+      debug('verify.error.emptyAlg');
+      return false;
+    }
+
+    const signerDid = body[signerKey];
+    if (!signerDid) {
+      debug('verify.error.emptySignerDid');
+      return false;
+    }
+
+    if (isFromPublicKey(signerDid, signerPk) === false) {
+      debug('verify.error.signerDidAndPkNotMatch');
+      return false;
+    }
+
+    if (enforceTimestamp) {
+      const now = Math.ceil(Date.now() / 1000);
+      const exp = Number(body.exp) || 0;
+      const iat = Number(body.iat) || 0;
+      const nbf = Number(body.nbf) || 0;
+      debug('verify.enforceTimestamp', { now, exp, iat, nbf });
+      if (exp && exp + tolerance < now) {
+        debug('verify.error.expired');
+        return false;
+      }
+      if (iat && iat > now && iat - now > tolerance) {
+        debug('verify.error.issuedAt');
+        return false;
+      }
+      if (nbf && nbf > now && nbf - now > tolerance) {
+        debug('verify.error.notBefore');
+        return false;
+      }
+    }
+
+    const signers = {
+      secp256k1: getSigner(types.KeyType.SECP256K1),
+      es256k: getSigner(types.KeyType.SECP256K1),
+      ed25519: getSigner(types.KeyType.ED25519),
+      ethereum: getSigner(types.KeyType.ETHEREUM),
+    };
+    const alg = header.alg.toLowerCase();
+    if (signers[alg]) {
+      const msgHex = toHex(`${headerB64}.${bodyB64}`);
+
+      // If we are using v1.1 protocol, the message should be hashed before verify
+      const version = body.version && semver.coerce(body.version) ? semver.coerce(body.version).version : '';
+      if (version && version === JWT_VERSION_REQUIRE_HASH_BEFORE_SIGN) {
+        return signers[alg].verify(hasher(msgHex), signature, signerPk);
+      }
+
+      return signers[alg].verify(msgHex, signature, signerPk);
+    }
+
+    debug('verify.error.crypto');
+    return false;
+  } catch (err) {
+    debug('verify.error.exception');
+    debug(err);
+    return false;
+  }
+};
+
+module.exports = {
+  sign,
+  verify,
+  decode,
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@arcblock/jwt",
+  "description": "JSON Web Token variant for arcblock DID solutions",
+  "version": "1.6.10",
+  "author": {
+    "name": "wangshijun",
+    "email": "shijun@arcblock.io",
+    "url": "https://github.com/wangshijun"
+  },
+  "contributors": [
+    "wangshijun <shijun@arcblock.io> (https://github.com/wangshijun)"
+  ],
+  "bugs": {
+    "url": "https://github.com/ArcBlock/asset-chain/issues",
+    "email": "shijun@arcblock.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@arcblock/did": "1.6.10",
+    "@ocap/mcrypto": "1.6.10",
+    "@ocap/util": "1.6.10",
+    "debug": "^4.3.3",
+    "json-stable-stringify": "^1.0.1",
+    "semver": "^7.3.4"
+  },
+  "devDependencies": {
+    "jest": "^27.3.1"
+  },
+  "homepage": "https://github.com/ArcBlock/asset-chain/tree/master/did/jwt",
+  "keywords": [
+    "blockchain",
+    "arcblock",
+    "sdk",
+    "nodejs"
+  ],
+  "license": "Apache-2.0",
+  "main": "./lib/index.js",
+  "files": [
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ArcBlock/asset-chain/tree/master/did/jwt"
+  },
+  "scripts": {
+    "lint": "eslint lib tests",
+    "lint:fix": "eslint --fix lib tests",
+    "test": "jest --forceExit --detectOpenHandles",
+    "coverage": "yarn test -- --coverage"
+  },
+  "gitHead": "ab272e8db3a15c6571cc7fae7cc3d3e0fdd4bdb1"
+}