sign-assistant-extension v0.1.8

Web Sign Assistant Extension

A Typescript library to communicate web pages with Sign Assistant compatible extensions

Getting started

You can install the module via npm or yarn:

yarn add sign-assistant-extension

npm install sign-assistant-extension --save

This library can only be used in frontend (browser). If its used in server side rendering (like Nextjs), please, make a dynamic import of the component that uses it.

Features

• Check if extension is installed and enabled
• Check if the Sign Assistant is installed
• Download extension based on current browser
• Download Sign Assistnat based on extension response
• Get certificate list from extension
• Sign a hash
• Listen to errors, requests and responses from extension

Examples

Here are some code examples.

Basic Usage

import Signer from 'sign-assistant-extension';

const signer = new Signer({
  key: "YOUR_KEY", // website sign assistant access key
  id: "extension-unique-id",
})

const loadCertificates = async () => {
  const certificates = await signer.getCertificates()
  console.log({ certificates })
}

loadCertificates()

Advanced Usage

import Signer, { isError } from 'sign-assistant-extension';
import toast from './toast';

const signer = new Signer({
  key: "YOUR_KEY", // website sign assistant access key
  id: "extension-unique-id",
})

const signWithFirstCertificate = async () => {
  const certificates = await signer.getCertificates() // sends error if not found extension or Sign Assistant

  const dataToSign = 'Q1VTVE9NIENPTlRFTlQ='
  const dataToSignArray = [{
    dataToSign, // string of data to sign
    key: 1,
  }]
  const certificate = certificates[0]
  const signResponse = await signer.sign({ dataToSignArray, certificate })
  
  if (isError(signResponse)) {
    toast(signResponse.error)
    return
  }
  console.log({ signature: signResponse[0].signature })
}

signWithFirstCertificate()

This library is strongly typed, but here are the method response type definitions to help you better understand its workings.

interface Certificate {
  isValid: boolean
  issuer: string
  name: string
  notAfter: string
  notBefore: string
  pem: string
  provider: string
  specialName: string
  type: string
  personId?: string
}

interface Signature {
  key: number
  signature: string
}

interface ErrorResponse {
  level: "BACKGROUND" | "CONTENT" | "CLI" | "LIB" | "EXTENSION_RUNTIME" // specify where the error occurred
  error: string // user friendly message
  code: number // code based on error level, explained later...
  originalErrorMessage?: string // original error message if it exist (set if level is "EXTENSION_RUNTIME" or "CLI")
}

Methods

List certificates

const searchResponse = await signer.getCertificates()
// will return: Certificate[] | ErrorResponse

Sign

const dataToSignArray = [{
  dataToSign, // string of data to sign
  key: 1,
}]
const signResponse = await signer.sign({ dataToSignArray, certificate })
// will return: Signature[] | ErrorResponse

Has Extension

const hasExtension = await signer.hasExtension() // timeout = 1000ms
// wil return: true | ErrorResponse

Has Software

const hasSoftware = await signer.hasSoftware() // timeout = 1000ms
// wil return: true | ErrorResponse

Download extension (Its not a Promise because download urls already setten in downloadLinks property)

const url = signer.downloadExtension({
  openUrl: false // Optional, default: true
})
// wil return: string | ErrorResponse
// string is the download url, it will be open as new tab if openUrl is not set to false

Download software

const url = await signer.downloadSoftware({
  openUrl: false // Optional, default: true
})
// wil return: string | ErrorResponse
// string is the download url, it will be open as new tab if openUrl is not set to false

Is error (narrow type check) - This method is also exported from library index

const dataToSignArray = [{
  dataToSign, // string of data to sign
  key: 1,
}]
const signResponse = await signer.sign({ dataToSignArray, certificate })
const isError = signer.isError(signResponse) // boolean
if (isError) {
  console.log(signResponse.error)
}
// will return: boolean

Properties

Error codes