PK-Docs: Polykey-Core Library - Getting Started Demo Docs

[CryptoTotalWar]

Introduction

This tutorial will guide developers on how to integrate the Polykey-Core Library into their applications to manage secrets programmatically. The aim is to enable the application to perform operations such as checking agent status, creating vaults, storing secrets, and retrieving them without using the CLI directly.

Objective

Equip developers with the knowledge to integrate Polykey operations within their applications, using the Polykey-Core Library to programmatically manage secrets.

Tasks

• Brian may choose to create his own sub-ticket here for the implementation example or just re-use the section below of this ticket for specing it out.
• Meeting to rMeet to review/discuss the implementation example (Pablo, Brian, Roger - optional)
• Planning & implementation of getting started documentation for Polykey-Core with Brian's demo example.
• (Optional): Create a sub-issue & schedule meeting with Brian to document the configuration necessary for getting a demo-ready terminal for potentially using asiinema (although on 2nd thought, this might be more relevant for PK-CLI related tutorials instead of the PK-Core tutorial)

The Following is some implementation detail examples i got back from GPT.

Prerequisites

• Basic knowledge of Node.js and asynchronous programming.
• An existing Node.js project environment or setup.
• Polykey-Core Library installed in the project.

Setup

Ensure the Polykey-Core Library is added to your project:

npm install polykey-core

Tasks

Task 1: Initialize Polykey Client

Create a Polykey client that connects to a Polykey node, handling initialization and connection:

const { PolykeyClient } = require('polykey-core');

async function initializePolykey() {
  const pkClient = await PolykeyClient.createPolykeyClient({
    nodeId: 'your-node-id', // replace with actual node ID
    host: 'localhost',
    port: 4433,
    options: { nodePath: 'path/to/node' },
  });
  return pkClient;
}

Task 2: Check Agent Status

Retrieve and print the status of the Polykey agent:

async function checkAgentStatus(pkClient) {
  const status = await pkClient.rpcClient.methods.agentStatus();
  console.log('Agent Status:', status);
}

Task 3: Create a Vault

Demonstrate how to create a new vault:

async function createVault(pkClient, vaultName) {
  await pkClient.rpcClient.methods.createVault({ vaultName });
  console.log(`Vault ${vaultName} created successfully.`);
}

Task 4: Add a Secret to the Vault

Add a file as a secret into the vault:

async function addSecret(pkClient, vaultName, secretName, secretData) {
  await pkClient.rpcClient.methods.addSecret(vaultName, secretName, secretData);
  console.log(`Secret ${secretName} added to vault ${vaultName}.`);
}

Task 5: Retrieve and Print the Secret

Fetch and print the secret from the vault:

async function retrieveSecret(pkClient, vaultName, secretName) {
  const secret = await pkClient.rpcClient.methods.getSecret(vaultName, secretName);
  console.log(`Retrieved Secret: ${secret}`);
}

Task 6: Clean up and Disconnect

Ensure proper cleanup and disconnection:

async function cleanup(pkClient) {
  await pkClient.stop();
  console.log('Polykey client disconnected and cleaned up.');
}

Full Workflow

Combine all steps to demonstrate a complete workflow within your application:

async function runPolykeyOperations() {
  const pkClient = await initializePolykey();
  await checkAgentStatus(pkClient);
  await createVault(pkClient, 'ExampleVault');
  await addSecret(pkClient, 'ExampleVault', 'MySecret', 'SecretData');
  await retrieveSecret(pkClient, 'ExampleVault', 'MySecret');
  await cleanup(pkClient);
}

runPolykeyOperations().catch(console.error);

Conclusion

This tutorial provides a step-by-step guide on how to integrate Polykey-Core Library functionalities into your application, allowing for programmatically managing secrets without the CLI.

[linear]

PRO-199 PK-Docs: Polykey-Core Library Tutorial

[CryptoTotalWar]

Mentioned this ticket again with @tegefaulkes in Cycle 10's Sync meeting.

It's a low-medium priority at the moment. It is being planned for implementation in cycle 11 or cycle 12. I'm going to move it to Cycle 11 at the moment.

Brian offered that he might be able to write up a quick demo example. He was the one who proposed the initial idea.

I think this might be the most appropriate use of time, having Brian write up a quick demo example of integrating the PK client library in a project, simulating CLI operations in the way that the code is executed in the project leveraging the client library and having comments in the codebase that explain the implementation and execution.

I can then take this and synthesize the information appropriately into the documentation.

However, it just occured to me that this might be a prime use-cases of situation where we would benefit greatly from using Asiinema.

This is something that I can do!!! However, like i mentioned, it would require a meeting to help me configure a terminal profile that doesn't have any of my home directory info included into it for more clarity.

This can be a sub-issue blocker ticket we create off of this ticket. Something I ca do with Brian AFTER he has made the example.