digitalcredentials / security-document-loader

A common documentLoader for DCC JSON-LD using libraries.
MIT License
0 stars 2 forks source link

JSON-LD Document Loader (@digitalcredentials/security-document-loader)

Build status NPM Version

A secure and convenient JSON-LD document loader for Node.js, browsers, and React Native.

Table of Contents

Background

Included functionality:

Security

TBD

Install

NPM

To install via NPM:

npm install @digitalcredentials/security-document-loader

Development

To install locally (for development):

git clone https://github.com/digitalcredentials/security-document-loader.git
cd security-document-loader
npm install

Usage

To get a default document loader (with the stock set of bundled contexts):

import { securityLoader } from '@digitalcredentials/security-document-loader'

const documentLoader = securityLoader().build()

To add additional contexts:

import { securityLoader } from '@digitalcredentials/security-document-loader'

const loader = securityLoader()
loader.addStatic('https://example.com/my-context/v1', contextObject)

const documentLoader = loader.build()

Fetching From the Web

To enable fetching arbitrary contexts from the web (not recommended, if you can avoid it):

const documentLoader = securityLoader({ fetchRemoteContexts: true }).build()

Supported URL Protocol Handlers

Out of the box, this library supports loading the following documents:

Additionally, if your use case allows it, you can enable fetchRemoteContexts, which will add support for URLs using the http and https protocols (see previous section).

Adding Custom Protocol Handlers

Sometimes you will need to add documents with other URL protocols. If you have internal code to resolve those protocols (for example, you can fetch some urn: documents from a local database), you can write a custom protocol handler:

import { securityLoader } from '@digitalcredentials/security-document-loader'

function getDocument (url) {
  // Some internal function that fetches or creates documents
}

const customResolver = {
  /**
   * @param {object} options - Options hashmap.
   * @param {string} options.url - Document URL (here `urn:...` key id)
   * @returns {Promise<object>} - Resolves with key object document.
   */
  async get(params: Record<string, string>): Promise<unknown> {
    let document
    try {
      document = await getDocument(params.url)
    } catch(e) {
      throw new Error('NotFoundError')
    }

    return document
  }
};

// For example, use your `getDocument` function to resolve all `urn:` URIs:
securityLoader.setProtocolHandler({protocol: 'urn', handler: customResolver})

const documentLoader = securityLoader().build()

Contribute

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

License

MIT License © 2022 Digital Credentials Consortium.