jlinc-sdk-node/README.md

JLINC NodeJS SDK

The JLINC NodeJS SDK serves as a centralized vehicle for leveraging all aspects of the core JLINC protocol. This library will enable you to build client/server applications that leverage built-in secure identity management, agreement signing, and data exchange provided via the protocol.

Details of the JLINC protocol, schema, and context can be found at: https://protocol.jlinc.io/.

Installation

npm install @jlinc/sdk

Sample usage

The below code sample is a demonstration of the JLINC NodeJS SDK in action. As data moves through the system, it is cryptographically signed with a unique key for each element in the system, and zero-knowledge audit records are delivered to the JLINC Archive Server.

const {
  jlincInit,
  jlincProduceEvent,
  jlincProcessEvent,
  jlincProduceAgreement,
  jlincProcessAgreement,
} = require("@jlinc/sdk");

async function main() {
  const config = {
    dataStoreApiUrl: process.env.JLINC_DATA_STORE_API_URL ?? "http://localhost:9090",
    dataStoreApiKey: process.env.JLINC_DATA_STORE_API_KEY,
    archiveApiUrl: process.env.JLINC_ARCHIVE_API_URL ?? "http://localhost:9090",
    archiveApiKey: process.env.JLINC_ARCHIVE_API_KEY,
    defaultAgreementId: "00000000-0000-0000-0000-000000000000",
    systemPrefix: process.env.JLINC_SYSTEM_PREFIX ?? "TestJlinc",
    debug: false,
  }
  jlincInit(config);

  try {

    let data;
    let r;

    // Define participants in this agreement and data exchange
    const entity1 = `EntityOne`;
    const entity2 = `EntityTwo`;

    console.log(`\nAction: Produce (create and sign) agreement`)
    data = {
      uri: 'http://localhost:9090/agreements/05c93a30cc699cfaee9185f23a5f68ffb12305acce1ca4b9444758fc4d594828',
      validRoles: ['provider', 'user'],
      purposes: ['testing'],
      caveats: ['production'],
      requiredSigners: [entity1],
      signer: entity1,
      role: 'provider',
    }
    r = await jlincProduceAgreement(data)
    if (r) {
      if (printResults) {
        console.log(`Result:`)
        console.log(`---------------------------------------------`)
        console.log(JSON.stringify(r, null, 2))
        console.log(`---------------------------------------------`)
      }
      if (r.created && r.processed) {
        console.log('PASS')
      } else {
        throw new Error('FAIL')
      }
    }
    const agreementId = r.created.agreementId

    console.log(`\nAction: Process (cross sign) agreement`)
    data = {
      agreementId,
      signer: entity2,
      role: 'user',
    }
    r = await jlincProcessAgreement(data)
    if (r) {
      if (printResults) {
        console.log(`Result:`)
        console.log(`---------------------------------------------`)
        console.log(JSON.stringify(r, null, 2))
        console.log(`---------------------------------------------`)
      }
      if (r.auditData && r.auditData.audit.agreementId === agreementId) {
        console.log('PASS')
      } else {
        throw new Error('FAIL')
      }
    }

    console.log(`\nAction: Produce (create and sign) event for data to be sent`)
    data = {
      from: entity1,
      to: entity2,
      agreementId,
      payload: {
        data: "testing",
      },
    }
    r = await jlincProduceEvent(data)
    if (r) {
      if (printResults) {
        console.log(`Result:`)
        console.log(`---------------------------------------------`)
        console.log(JSON.stringify(r, null, 2))
        console.log(`---------------------------------------------`)
      }
      if (r.created && r.processed && r.created.agreementId === agreementId) {
        console.log('PASS')
      } else {
        throw new Error('FAIL')
      }
    }
    const eventId = r.created.eventId;

    console.log(`\nAction: Process (sign) by the receiver after data is sent`)
    data = {
      to: entity2,
      eventId,
    }
    r = await jlincProcessEvent(data)
    if (r) {
      console.log(`Result:`)
      if (printResults) {
        console.log(`---------------------------------------------`)
        console.log(JSON.stringify(r, null, 2))
        console.log(`---------------------------------------------`)
      }
      if (r.auditData && r.auditData.audit.eventId === eventId) {
        console.log('PASS')
      } else {
        throw new Error('FAIL')
      }
    }

    console.log(`\nAction: Produce (create and sign) event for data to be sent with successful auth`)
    data = {
      from: entity1,
      to: entity2,
      auth: {
        subject: {
          type: "user",
          id: "tester",
        },
        action: {
          name: "read",
        },
        resource: {
          type: "data",
          id: "1234",
          properties: {
            ownerID: "tester@test.com",
          }
        }
      },
      payload: {
        data: "testing",
      },
    }
    r = await jlincProduceEvent(data)
    if (r) {
      if (printResults) {
        console.log(`Result:`)
        console.log(`---------------------------------------------`)
        console.log(JSON.stringify(r, null, 2))
        console.log(`---------------------------------------------`)
      }
      if (r.created && r.processed) {
        console.log('PASS')
      } else {
        throw new Error('FAIL')
      }
    }

    console.log(`\nAction: Produce (create and sign) event for data to be sent with failed auth`)
    data = {
      from: entity1,
      to: entity2,
      auth: {
        subject: {
          type: "user",
          id: "tester",
        },
        action: {
          name: "write",
        },
        resource: {
          type: "data",
          id: "1234",
          properties: {
            ownerID: "tester@test.com",
          }
        }
      },
      payload: {
        data: "testing",
      },
    }
    r = await jlincProduceEvent(data)
    if (r) {
      if (printResults) {
        console.log(`Result:`)
        console.log(`---------------------------------------------`)
        console.log(JSON.stringify(r, null, 2))
        console.log(`---------------------------------------------`)
      }
      if (r.decision != undefined && r.decision == false) {
        console.log('PASS')
      } else {
        throw new Error('FAIL')
      }
    }

  } catch (err) {
    console.error("[*] ERROR:", err);
  }

}

main()

API Reference

jlincInit(data: JLINCConfig)

Call jlincInit before using any other method. The configuration object supports the following properties:

Key	Type	Default	Description
dataStoreApiUrl	string	http://localhost:9090	Base URL for the data store API
dataStoreApiKey	string		Bearer token for authenticating API requests
archiveApiUrl	string	http://localhost:9090	URL for the archive service
archiveApiKey	string		API key for the archive service
systemPrefix	string	my-system	(Optional) Prefix applied to all entity short names
domain	string	Server Specified	(Optional) Default domain for entities. If not specified, it is auto-resolved on first call
defaultAgreementId	string	00000000-0000-0000-0000-000000000000	(Optional) Default agreement ID for events
debug	boolean	false	(Optional) Enables verbose console logging for requests/responses

jlincProduceAgreement(data: JLINCProduceAgreementData)

Creates and publishes a new agreement.

Parameters:

Key	Type	Description
requiredSigners	Array<string>	List of entities required to sign
signer	string	The entity producing/signing this request
uri	string	Resource URI the agreement applies to
purposes	Array<string>	Allowed purposes under the agreement
caveats	Array<string>	Prohibitions under the agreement
validRoles	Array<string>	Allowed roles for the agreement
role	string	The role being signing the agreement
auth	object	(Optional) AuthZEN authentication data

jlincProcessAgreement(data: JLINCProcessAgreementData)

Signs an existing agreement.

Parameters:

Key	Type	Description
agreementId	string	The ID of the agreement to process
signer	string	The entity signing the agreement
role	string	The role being signed on behalf of
auth	object	(Optional) AuthZEN authentication data

jlincProduceEvent(data: JLINCProduceEventData)

Creates and publishes a new event.

Parameters:

Key	Type	Description
from	string	The entity sending and signing the data
to	string	The entity to receive the data
agreementId	string	(Optional) Agreement ID. Falls back to defaultAgreementId if omitted
payload	any	The data payload to send
auth	object	(Optional) AuthZEN authentication data forwarded to the API

jlincProcessEvent(data: JLINCProcessEventData)

Signs an existing agreement.

Parameters:

Key	Type	Description
to	string	The entity receiving and signing the data
eventId	string	The ID of the event to process
auth	object	(Optional) AuthZEN authentication data