289 lines
9.2 KiB
Markdown
289 lines
9.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```js
|
|
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 |
|