From f121ea9622f0588f1b2ff952e1dd1019e812eaff Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Thu, 27 Mar 2025 10:28:18 -1000 Subject: [PATCH 1/6] feat: New Landing Page and Sidebars, Documents, Updates --- docs/Getting-Started/polykey-cli/README.md | 81 +++ .../polykey-cli/bootstrapping.md | 151 ++++++ .../claiming-digital-identities.md | 217 ++++++++ .../polykey-cli/discovering-other-users.md | 220 ++++++++ .../polykey-cli/installation.md | 468 ++++++++++++++++++ .../polykey-cli/managing-multiple-nodes.md | 164 ++++++ .../polykey-cli/managing-secrets.md | 389 +++++++++++++++ .../polykey-cli/managing-vaults.md | 136 +++++ .../polykey-cli/sharing-vaults.md | 130 +++++ .../using-environment-variables.md | 171 +++++++ docs/Getting-Started/polykey-core/README.md | 5 + .../polykey-core/installation.md | 118 +++++ docs/README.md | 19 +- sidebars.ts | 2 +- 14 files changed, 2258 insertions(+), 13 deletions(-) create mode 100644 docs/Getting-Started/polykey-cli/README.md create mode 100644 docs/Getting-Started/polykey-cli/bootstrapping.md create mode 100644 docs/Getting-Started/polykey-cli/claiming-digital-identities.md create mode 100644 docs/Getting-Started/polykey-cli/discovering-other-users.md create mode 100644 docs/Getting-Started/polykey-cli/installation.md create mode 100644 docs/Getting-Started/polykey-cli/managing-multiple-nodes.md create mode 100644 docs/Getting-Started/polykey-cli/managing-secrets.md create mode 100644 docs/Getting-Started/polykey-cli/managing-vaults.md create mode 100644 docs/Getting-Started/polykey-cli/sharing-vaults.md create mode 100644 docs/Getting-Started/polykey-cli/using-environment-variables.md create mode 100644 docs/Getting-Started/polykey-core/README.md create mode 100644 docs/Getting-Started/polykey-core/installation.md diff --git a/docs/Getting-Started/polykey-cli/README.md b/docs/Getting-Started/polykey-cli/README.md new file mode 100644 index 00000000..f2f6489b --- /dev/null +++ b/docs/Getting-Started/polykey-cli/README.md @@ -0,0 +1,81 @@ +import DocCardList from '@theme/DocCardList'; + +# Polykey CLI + +The Polykey Command Line Interface (CLI) is the primary user interface for the +Polykey system, tailored for developers and system administrators. It was +conceived from the necessity of managing secrets efficiently during software +development and deployment workflows. + +## Overview + +The Polykey CLI is the first and primary interface to the Polykey system. It is +intended for developers and system administrators who require an advanced tool +for managing secrets efficiently. New features are introduced in the CLI first, +serving as a testing and integration ground before being ported to other user +interfaces. This approach ensures that the features are reliable and refined for +professional use. + +We designed the CLI user-experience (UX) to be suitable for a human operator, +but also to be easily scripted and integrated into other tools. + +The tutorial here should be followed in order, and the goal is to make use of +Polykey to manage secrets for a simple application from development to +deployment. + +The CLI is open-source and available on GitHub: +[Polykey CLI](https://github.com/MatrixAI/Polykey-CLI). + +### Supported Platforms + +Polykey is continuously built and tested on: + +- Linux x64 / arm64 +- MacOS x64 / arm64 +- Windows x64 +- Docker + +:::note Polykey is currently in beta. Its interface is at various levels of +stability. So bear with us as we perfect its design. You can contribute by +discussing with us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue +tickets in the +[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). ::: + +## Getting Started + +Start your journey with Polykey by following the tutorials below in sequence: + +:::tip For a visual walkthrough, check out our +[getting started demo video](https://vimeo.com/884649667) after installing +Polykey. ::: + +1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install + Polykey CLI on your platform. +2. **[Bootstrap Keypair](/docs/tutorials/polykey-cli/bootstrapping)** - Set up + your node and connect to the network. +3. **[Managing Vaults](/docs/tutorials/polykey-cli/managing-vaults)** - Securely + store secrets within encrypted vaults. +4. **[Managing Secrets](/docs/tutorials/polykey-cli/managing-secrets)** - + Organize and handle secrets within your vaults. +5. **[Claiming Digital Identities](/docs/tutorials/polykey-cli/claiming-digital-identities)** - + Establish and authenticate your identity within the network. +6. **[Discovering Other User's Identities](/docs/tutorials/polykey-cli/discovering-other-users)** - + Find and verify other users to manage permissions. +7. **[Sharing Vaults](/docs/tutorials/polykey-cli/sharing-vaults)** - Share your + encrypted vaults securely with peers. +8. **[Managing Multiple Nodes](/docs/tutorials/polykey-cli/managing-multiple-nodes)** - + Operate multiple local nodes/agents. +9. **[Using Environment Variables](/docs/tutorials/polykey-cli/using-environment-variables)** - + Master `polykey secrets env` for dynamic environment management. + +Explore advanced scenarios in subsequent sections, including: + +- Managing multiple local nodes +- Integrating multiple nodes with a single identity +- Injecting secrets directly into your development environments using Polykey’s + `env` command + +This will prepare you to fully exploit Polykey’s capabilities in diverse and +complex operational settings. + + diff --git a/docs/Getting-Started/polykey-cli/bootstrapping.md b/docs/Getting-Started/polykey-cli/bootstrapping.md new file mode 100644 index 00000000..44aeb7c8 --- /dev/null +++ b/docs/Getting-Started/polykey-cli/bootstrapping.md @@ -0,0 +1,151 @@ +# Bootstrapping + +## Introduction + +Bootstrapping is the process where the Polykey agent sets itself up as a new +Polykey node. This involves creating the encrypted-at-rest node state, and +connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified +network domain. + +## Setting Up Your Node + +### Creating the Root Key + +When you first start the Polykey agent, it automatically generates a random root +key. + +This root key is an asymmetric key pair consisting of a public key representing +your identity and used for verifying signatures, and a private key which is used +for signing. + +Afterwards, encryption keys are derived from this root key, which is used for +encryption and decryption of all node state and secret data managed by Polykey. + +You will be prompted to provide a root password. This password encrypts the root +key. + +:::note Remember to keep your password in a secure location as you will need it +each time you start the Polykey agent. ::: + +### Starting the Polykey Agent + +You can start the Polykey agent in the foreground of your terminal by running: + +```bash +polykey agent start --verbose +``` + +Running the agent in the foreground allows you to monitor its output directly in +the terminal. Ensure this terminal session remains active to keep the agent +running. You can execute Polykey commands from any other terminal session while +this runs. + +### Starting Polykey in the Background + +Alternatively, in the demo video and other scenarios where you do not wish to +occupy your terminal, you can start the agent in the background: + +```bash +polykey agent start --verbose --background +``` + +### Stopping the Polykey Agent + +You can stop the Polykey agent by pressing **Control+C** in the terminal where +it's running in the foreground, or by running: + +```bash +polykey agent stop +``` + +#### Troubleshooting + +If the Polykey agent does not terminate properly, you can force quit the process +through the Activity Monitor on your machine. If you encounter this or any other +issue, please consider making a +[bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) to help +improve Polykey. + +## Check Agent Status + +To check the status of your Polykey node, use the following command: + +```bash +polykey agent status +``` + +This command provides detailed information about your node's current state, +including its connectivity and activity within the network. + +### Example Output + +```bash +status LIVE +pid 96992 +nodeId vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg +clientHost ::1 +clientPort 54975 +agentHost :: +agentPort 60358 +upTime 8 +startTime 1716509093 +connectionsActive 3 +nodesTotal 11 +version 1.2.3-alpha.4-1-1 +sourceVersion 1.2.3-alpha.4 +stateVersion 1 +networkVersion 1 +``` + +## Check Network Status + +When your agent has started, it should show as a node on the network. By default +the network is [mainnet](https://mainnet.polykey.com/). Check out the network +dashboard to see your placement on the world map. + +## Monitoring Network Connections + +To view the nodes currently connected to the network, including the seed nodes, +run: + +```bash +polykey nodes connections +``` + +This will list all active connections, including details about each node. + +### Example Output + +```bash +host hostname nodeIdEncoded port timeout usageCount +3.145.86.40 N/A v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0 1314 46873 0 +13.239.117.143 N/A vncm2mkk41vgp2fmplqiu1je7b2l3v6fhgltlqf5f3f85923ve0j0 1314 116186 0 +1.145.55.96 N/A vg6gldhfdstju8frtbguav2p2svmev85dvpdb34gffmiagpgjf2pg 1200 102086 0 +``` + +## Checking Node Activity + +To determine if a specific node is active, use the ping command: + +```bash +polykey nodes ping +``` + +This will tell you whether the node is active within the network. + +### Example Output + +```bash +polykey nodes ping v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0 +Node is Active +``` + +## Conclusion + +Bootstrapping your node is the first step to using Polykey effectively. It +prepares your node for managing and sharing secrets securely within the network. +By following these guidelines, you ensure that your node is well-configured, +secure, and ready for advanced operations in the Polykey ecosystem. + +Stay tuned for upcoming sections where we will discuss managing multiple nodes, +assigning different file paths to each node, and other advanced configurations. diff --git a/docs/Getting-Started/polykey-cli/claiming-digital-identities.md b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md new file mode 100644 index 00000000..3a093a1c --- /dev/null +++ b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md @@ -0,0 +1,217 @@ +# Claiming Digital Identities: Establishing Identity Linkages in Polykey + +In Polykey, claiming a digital identity is a crucial step that allows users to +establish their identity across various platforms and link these identities to +their cryptographic keys. This process involves authenticating with external +services, such as GitHub, and claiming ownership of an identity by posting a +cryptographic link to a publicly verifiable location. + +This tutorial will guide you through the steps to authenticate with GitHub and +claim an identity using Polykey, enhancing security and streamlining identity +verification, making it easier for other users to discover and trust your nodes. + +## Step 1: Authenticate with GitHub + +Authentication with a service provider like GitHub is the first step toward +claiming your digital identity. This process allows Polykey to interact with +GitHub on your behalf and access necessary information to claim your identity. + +![GitHub Authentication](/images/github-authentication.png) + +_This image provides a demo example of the GitHub authentication process._ + +### Command Usage + +:::info + +```bash +polykey identities authenticate +``` + +``: The identifier for the digital identity provider, such as +"github". ::: + +:::note Since Polykey currently only supports GitHub as an IdP, this is the +command that you will use to start the authentication process. + +```bash +polykey identities authenticate github +``` + +::: + +This command begins the authentication process with GitHub. Follow the prompts +in your terminal to complete the authentication, which may involve logging into +your GitHub account and authorizing Polykey to access your GitHub information +via a popup window. + +:::tip The code prompted by the browser will be displayed in your terminal as +the user code. ::: + +### Lists all authenticated identities across all providers + +`polykey identities authenticated` command will output the providerID and +corresponding identityID of the authenticated IdP. This is a way to check that +you completed the authentication process correctly. + +#### Example Usage + +```bash +polykey identities authenticated +``` + +##### Example Output + +```bash +providerId github.com +identityId maverick +``` + +### Technical Use of Permissions + +During the authentication process, here's what Polykey requests access to and +why: + +- **Create Gists:** Polykey creates a gist under your GitHub account containing + a cryptographic link. This link is a verifiable method that proves the + ownership of your GitHub identity to anyone checking your Polykey gestalt + graph. + +- **Read All User Profile Data:** This enables Polykey to access your profile + details, including your username, followers, and public repository data. This + information is used to ensure that the identity you claim corresponds + accurately to your public digital footprint, enhancing trust and verification. + +- **Access User Email Addresses (read-only):** By accessing the email addresses + associated with your account, Polykey can better manage notifications related + to your secrets operations. + +#### Security and Privacy Considerations + +Polykey is committed to maintaining the highest standards of security and +privacy. All data accessed is used strictly for the operations mentioned and is +not shared with any third parties. Our privacy practices are designed to protect +your information and ensure its confidentiality. For more details, please refer +to our [privacy policy](https://polykey.com/privacy-policy). + +## Step 2: Claim Your Identity + +After successfully authenticating with GitHub, you can claim your identity. This +involves posting a cryptographic link to a publicly verifiable location, such as +a GitHub gist. This link serves as proof of ownership of the identity. + +Cryptolink + +### Command Usage + +_This image provides a demo example of the cryptographic link that is +generated._ + +:::info + +- ``: The specific identity identifier from the provider you + authenticated with, which you will claim. + +- `polykey identities claim` argument for `` = `github.com`+ + `:` + `GH username` + +::: + +Replace `my-gh-username` with your actual GitHub username. This command claims +your GitHub identity by posting a cryptographic link to a gist under your GitHub +profile. + +```bash +polykey identities claim github.com:my-gh-username +``` + +## Step 3: Verify Your Claim + +After claiming your identity, Polykey provides a link to a GitHub gist in your +terminal. This is your primary method to verify that your identity has been +correctly claimed. + +![Claim Id](/images/claim-id.png) + +_This image shows a demo example of the link to the gist that was created when +claiming the identity which forms a gestalt._ + +### Primary Verification Method + +Check your GH gists. Replace `my-github-username` with your actual gh username +and navigate to the url. + +```bash +https://gist.github.com/my-github-username +``` + +This gist contains the cryptographic link confirming that your Polykey identity +is correctly linked to your GitHub profile. Viewing this gist ensures your claim +was successful and publicly verifiable. + +## Understanding Gestalt Graphs + +In Polykey, claiming identities creates a **gestalt graph**—a dynamic, +interconnected network of your digital identities across various platforms. This +graph facilitates the federated identity model, allowing for more robust and +streamlined identity verification and management. + +![gestalts](/images/gestalts.png) + +_This image shows a federated gestalt graph example concept map._ + +### How Gestalt Graphs Work + +Each node within the graph represents an identity or a claim, and edges +represent trust relationships or cryptographic verifications. As you claim more +identities or add nodes, the graph expands, enhancing its utility by making +identity verification straightforward and trust relationships more transparent. + +### Claiming Multiple Identities + +Polykey enables you to manage your digital presence flexibly by supporting the +claiming of multiple identities across different scenarios. Specifically, you +can: + +- Link one node to several identity providers (IdPs), broadening your digital + footprint and verification avenues as more IdPs are supported. + +- Claim the same identity provider, such as a GitHub username, across multiple + unique nodes you control, consolidating your digital identity while expanding + your network's reach. + +### Future Plans and IdP Support + +Currently, Polykey supports GitHub as an identity provider (IdP). However, we +are actively working to expand our support to include a wider range of major +IdPs. This expansion will enhance Polykey's accessibility and versatility, +accommodating a broader user base. Additionally, organizations will have the +option to maintain their own IdPs, allowing for even greater customization and +control over identity management within Polykey. + +### Benefits of Federated Identities + +Using a federated identity model through gestalt graphs offers several benefits: + +- **Enhanced Security**: By linking various identity proofs, it strengthens the + authenticity and credibility of your digital identity. +- **Simplified Management**: Manage multiple identities through a single + interface, reducing complexity and improving user experience. +- **Interoperability:** Easily interact across different platforms and services + using a unified identity framework. + +Understanding and utilizing gestalt graphs in Polykey not only secures your +operations but also significantly simplifies the process of digital identity +management. + +## Conclusion + +Claiming your digital identity in Polykey links your cryptographic operations to +external accounts like GitHub, securing your operations and facilitating +identity verification by others. This guide details the essential steps for +authenticating, claiming, and verifying your identity in Polykey. + +In the next section, we will explore additional operations related to digital +identity management in Polykey, including discovery of other users, trust +management and permissions handling. diff --git a/docs/Getting-Started/polykey-cli/discovering-other-users.md b/docs/Getting-Started/polykey-cli/discovering-other-users.md new file mode 100644 index 00000000..abccd71d --- /dev/null +++ b/docs/Getting-Started/polykey-cli/discovering-other-users.md @@ -0,0 +1,220 @@ +# Discovering Users' Nodes and Managing Access Permissions + +In the Polykey network, discovering other users' nodes and managing access +permissions is crucial for secure and efficient collaboration. This guide will +walk you through the process of finding other users' nodes using their claimed +digital identities and setting permissions to manage how these nodes interact +with your secrets and vaults. + +## Introduction to Node Discovery and Permission Management + +Discovering nodes in Polykey involves locating other users within the network +who have linked their identities, such as GitHub usernames, to their nodes. Once +these nodes are discovered, you can manage access permissions to control how +these nodes interact with your shared resources. + +This functionality enhances the security of your network by ensuring that only +trusted nodes can access sensitive information. + +## Discovering Nodes + +To begin discovering nodes associated with known identities, you can use the +`polykey identities discover` command. This command adds a node or identity to +your discovery, facilitating further interactions like sharing vaults or +secrets. + +### Command Usage + +```bash +polykey identities discover +``` + +- ``: This can be either a Node ID or a `Provider ID:Identity ID` + combination that specifies the digital identity linked to the node you wish to + discover. + +#### Example + +```bash +polykey identities discover github.com:maverick +``` + +This command adds the node associated with the GitHub username "maverick" to +your discovery queue, allowing you to initiate interactions with this user. +:::note + +## Troubleshooting Discovery and Connection Issues + +When attempting to discover other users' nodes and manage permissions within +Polykey, there are specific requirements and common issues you may encounter. +Understanding and addressing these can ensure smoother operations within the +network. + +### Requirements for Successful Discovery + +1. **Active Polykey Agents:** Both users involved in the discovery must have + their Polykey agents actively running. This ensures that both nodes are + reachable and responsive within the network. + +2. **Network Connection:** Both nodes need to be connected to the Polykey + network. Currently, both users must be online simultaneously for the + discovery process to succeed. + +### Common Issues and Solutions + +1. **Gestalt Creation:** Ensure that the user you are trying to discover has + already created their gestalt. A gestalt is necessary for the identity to be + discoverable in the network. Without it, the discovery process will fail. + +2. **Symmetric NAT or Restrictive Networks:** Connection issues can arise if one + or both users are behind symmetric NATs or other restrictive network setups. + These environments can block the necessary network communications for + successful node discovery. + + - **Solution:** Attempt the discovery process from a network with less + restrictive settings, such as home Wi-Fi or a less secure public network, + to see if the issue persists. + +::: + +:::info + +### Future Enhancements + +Polykey is actively working to enhance the discovery process by implementing +features that would allow one-sided connectivity. This means that in the future, +users may not need to be online simultaneously. One user could initiate a +discovery, akin to sending a friend request, and the other could respond at +their convenience, simplifying the process and reducing the dependency on +simultaneous network presence. + +This section helps users understand the prerequisites for successful node +discovery and provides solutions to common issues that might impede the process. +By following these guidelines, users can more effectively manage their +interactions within the Polykey network. ::: + +## GestaltId and Permissions Explained + +### GestaltId + +The `gestaltId` is a unique identifier that directly links to a node or an +identity within the Polykey network. It can take the following forms: + +- **Node ID:** Directly references a node within the Polykey network. + +- **Provider ID:** Utilizes an identity provider (like GitHub) combined with a + specific user identity (like a username). + +#### Example Format + +- Node ID: `v60g23b4b9g5tq2npc3kpikpalqqdpuvocegdd8bsdj28a1hsp0g0` +- Provider ID: `github.com:maverick` + +### Permissions + +Permissions in Polykey determine what actions a node or an identity can perform +within the network. Here’s a general list of potential permissions that can be +managed: + +- **Read:** Allows viewing but not modifying. +- **Write:** Allows both viewing and modifying. +- **Execute:** Allows performing specific actions. +- **Notify:** Allows sending notifications about changes or updates. +- **Trust:** Allows a node to be trusted, generally affecting how interactions + are secured. + +#### Example Command to Set Permissions + +```bash +polykey identities allow github.com:maverick read write +``` + +## Managing Permissions + +Once a node is discovered, you can manage permissions to control access to your +vaults and secrets. Polykey allows you to set or unset permissions for each +discovered node or identity. + +### Setting Permissions + +To grant specific permissions to a node, use the `polykey identities allow` +command: + +```bash +polykey identities allow +``` + +- `:` The Node ID or `Provider ID:Identity ID` of the node. +- `:` The type of permission you want to allow, such as `read`, + `write`, or `execute`. + +#### Example + +```bash +polykey identities allow github.com:maverick read +``` + +This command grants read permissions to the node associated with the GitHub user +"maverick." + +### Revoking Permissions + +If you need to revoke permissions from a node, you can use the +`polykey identities disallow` command: + +```bash +polykey identities disallow github.com:maverick read +``` + +#### Example + +```bash +polykey identities disallow github.com:maverick read +``` + +This command revokes read permissions from the node associated with "maverick." + +## Additional Management Features + +Polykey also supports inviting nodes to your network, listing all discovered +nodes and their permissions, and setting trust levels for more granular control. + +### Inviting a Node + +To invite another node to join your network and potentially share secrets: + +```bash +polykey identities invite +``` + +### Listing Nodes and Permissions + +To view all nodes and their permissions within your network: + +```bash +polykey identities list +``` + +### Trusting and Untrusting Nodes + +You can explicitly trust or untrust a node to refine how notifications and +access controls are handled: + +```bash +polykey identities trust +polykey identities untrust +``` + +## Conclusion + +Managing node interactions and user discovery in Polykey is vital for +maintaining a secure and efficient network. By carefully managing who can access +your nodes and how they can interact with your resources, you enhance the +overall security and functionality of your network. + +This guide has provided the steps and commands necessary to effectively discover +nodes and manage permissions within Polykey. + +This addition ensures users understand the significance and usage of `gestaltId` +and permissions within the context of discovering and managing nodes in Polykey, +providing clear and actionable information for efficient network management. diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md new file mode 100644 index 00000000..adf69156 --- /dev/null +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -0,0 +1,468 @@ +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + +# Installation + +Installing the CLI can be done in different ways depending on your operating +environment. + +:::info + +Polykey-CLI has only been tested on Linux and macOS. We are working on +supporting other platforms. There's minor teething problems when it comes +supporting other platforms. Help us by reporting any issues with the CLI tool in +our Github Repo +[here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping +a message to the developers in our discord server +[here](https://discord.gg/dC32r35TeE). + +::: + + + + +## Linux + +Polykey-CLI code is compiled, bundled and wrapped into a single file executable. +You just have to download the executable, give it executable permissions and run +it. The executable is not statically linked. It requires a subset of the system +libraries that Node.js requires. + +- `libdl.so.2` +- `libstdc++.so.6` +- `libm.so.6` +- `libgcc_s.so.1` +- `libpthread.so.0` +- `libc.so.6` + +### Manually + +Builds for Linux is released on GitHub: +https://github.com/MatrixAI/Polykey-CLI/releases. + +Download the executable named `...-polykey-cli-V.V.V-linux-x64`, and rename it +to `polykey`. + +Make it executable: + +```sh +$ chmod u+x ./polykey +``` + +### Add it to your `$PATH`. + +#### For ZSH: + +1. `cd` into directory where polykey exec is stored. +2. Edit the zsh config to add polykey to your path. To streamline the process, + run the following command, making sure to change the path to polykey if the + polykey executable is not in the downloads folder. +3. For most users, this would be `~/Downloads` + +:::warning + +Make sure your path to the polykey executable is correct. + +::: + +```sh +$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc +``` + +You only need to run this command once. After running this command, you can now +invoke polykey by typing `polykey` into the terminal. + +--- + +#### For Bash: + +1. `cd` into directory where polykey exec is stored. +2. Edit the zsh config to add polykey to your path. To streamline the process, + run the following command, making sure to change the path to polykey if the + polykey executable is not in the downloads folder. +3. For most users, this would be `~/Downloads` + +:::warning + +Make sure your path to the polykey executable is correct. + +::: + +```sh +$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc +``` + +You only need to run this command once. After running this command, you can now +invoke polykey by typing `polykey` into the terminal. + +--- + +### NixOS + +We have not yet published a Nix package for Polykey. When we do, you will be +able to just install `polykey-cli` from Nixpkgs. + +However, it is easy enough to install it from source. + +Clone the repository: + +```sh +$ git clone https://github.com/MatrixAI/Polykey-CLI.git +``` + +Enter the `nix-shell`: + +```sh +$ nix-shell +``` + +Build the application and install it into the user profile: + +```sh +$ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)" +``` + +### Other + +We will be working on other distribution methods. + + + + +## MacOS + +:::info + +ARM-64 builds are not currently supported on MacOS as of **26-03-24.** However, +building Polykey yourself on MacOS resolves in a working binary. Follow this +guide below to manually build and install Polykey on macOS. + +::: + +### Manually + +1. Download the Polykey CLI for macOS from the + [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases). + Look for the file named `polykey-cli-V.V.V-darwin-universal`, where `V.V.V` + is the version number. For Mac, you want to download the file with the + `darwin-universal` file extension. + +2. Rename the downloaded file to `polykey` for easier access. In your terminal, + make sure to navigate to the directory where the file is located (usually the + Downloads directory) and run the following command: + +```sh + mv polykey-cli-V.V.V-darwin-universal polykey +``` + +:::tip + +- Navigate into the directory where the file is saved to execute commands. +- Replace `V.V.V.` with the actual version number of the file you downloaded. + +::: + +3. Make the Executable Runnable: Before you can run the Polykey CLI, you need to + make it executable. Use the `chmod +x` command to add executable permissions + to the file. Replace `polykey` with the actual name of your file if it's + different: + +```sh +chmod +x polykey +``` + +--- + +### MacOS Security Bypass + +MacOS requires additional steps for the binary to be allowed to execute, this is +due to the fact that as of 20-12-23, the binaries we release are unsigned, and +MacOS permits running of unsigned binaries, however, to progress past this, +there are a couple options: + + + + + #### Method #1 - quickest method + +The `xattr` command will remove the quarantine attribute from the Polykey +executable, allowing you to run it without triggering macOS security warnings. +Remember to ensure that the file path matches the location of your polykey file. + +```sh +sudo xattr -r -d com.apple.quarantine ~/Downloads/polykey +``` + +If you have completed this sucesfully, you may ignore Method #2 and move to the +next section on how to add polykey to your `$PATH`. + +## + +--- + + + + +#### Method #2 - Using the Apple Systems Settings GUI + +First type the following command to try running the Polykey CLI but will instead +trigger a pop-up. + +```sh +./polykey --version +``` + +1. MacOS will then prompt you with the following: + +:::important Do not close this prompt. If you do, the 'Allow Anyway' option will +not appear in the next step. ::: + +![install1](/images/mac-install1.png) + +2. While keeping the prompt open, head over to `Settings -> Privacy & Security` + and scroll down till you see '"polykey" was blocked from use because it is + not from an identified developer.' + +![install2](/images/mac-install2.png) + +3. Click on `Allow Anyway` and authenticate. + +4. Try opening polykey with + +```shell +sudo ./polykey +``` + +:::tip When prompted in the terminal, type your administrator password and hit +enter. ::: + +5. Following this, you will get another similar prompt + +![install3](/images/mac-install3.png) + +#### Click on Open and now Polykey-CLI should be running in your terminal window. + +:::tip You can also verify the version of polykey that was installed with: + +```sh +./polykey --version +``` + +::: + +--- + + + + +### Add Polykey to your `$PATH`. + +To enable running the Polykey CLI from any directory in the terminal on macOS, +you'll need to update your shell configuration file. + + + + +#### For ZSH (default shell on recent macOS versions): + +1. Navigate (cd) into the directory where the "polykey" executable is stored. + +2. Edit the Zsh configuration file to add "polykey" to your $PATH. Use the + following command, ensuring to replace ~/Downloads with the correct path to + the "polykey" executable if it's not in the downloads folder. For most users, + this path would be ~/Downloads on Debian-based systems. + +:::tip + +Make sure your path to the "polykey" executable is correct. + +::: + +```sh +echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc +``` + + + + +#### For Bash: + +1. `cd` into the directory where the "polykey" executable is stored. +2. Edit the Bash config to add "polykey" to your path. To streamline the + process, run the following command, making sure to change the path to + "polykey" if the executable is not in the downloads folder. For most users, + this would be `~/downloads` on Debian-based systems. + +:::tip + +Make sure your path to the "polykey" executable is correct. Replace `downloads` +with the path to the working directory + +::: + +```sh +echo 'export PATH=~/downloads:$PATH' >> ~/.bashrc && source ~/.bashrc +``` + + + + +:::tip + +You can check if the PATH environment variable for Polykey has been updated +correctly by running: + +```sh +polykey --version +``` + +If this command returns the current version, then you have successfully added +Polykey to your PATH, and you can now run polykey from anywhere in your +terminal. + +::: + + + + +:::warning + +Polykey for windows should be working but we have yet to create documentation on +the installation process for this. + +::: + + + + +## Docker + +The Docker image can be used so that Polykey can be deployed into the cloud. It +is also possible to use the CLI via the docker container, but it isn't as +convenient. The intention is to run the Polykey agent in the cloud. + +Docker images is released on GitHub: +https://github.com/MatrixAI/Polykey-CLI/releases. + +Download the image named `...-docker-image-polykey-cli-V.V.V.tar.gz` and rename +it to `docker-image-polykey-cli.tar.gz`. + +Load it into Docker: + +```sh +loaded="$(docker load --input "$(nix-build ./release.nix --attr docker --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)")")" +image="$(cut -d' ' -f3 <<< "$loaded")" +docker run -it "$image" +``` + +### Docker for Mac + +:::tip + +You can install nix for MacOS and then follow the general docker instructions +above. Nix for mac can be installed by running + +```sh +sh <(curl -L https://nixos.org/nix/install) +``` + +::: + +1. Download the latest build of Polykey-CLI for docker from + https://polykey.com/download. + +2. Download Docker for MacOS depending on your instruction-set (arm vs x86) from + https://docs.docker.com/desktop/install/mac-install/ + +3. Rename the Polykey dist from + `x-docker-image-polykey-cli-x.x.x-alpha.x.tar.gz` to `docker-polykey.tar.gz` + +4. Load the image in docker using the following: + +```shell +docker load --input docker-polykey.tar.gz +``` + +5. Go to your docker application and configure the Polykey image + +![img.png](/images/docker-mac-img1.png) + +6. Run `mkdir /tmp/polykey` to create a directory for the polykey nodepath + +7. Set the volume host path to `/tmp/polykey` and the container path to + `/tmp/polykey/` + +8. Run `docker images` to grab the Image ID of your installed image. + +```shell +> docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +polykey-cli-0.1.2-alpha.2 gygbx1qgpnhbvbcbaby3sfm19bamg7sx 0e1addd9855a 12 days ago 370MB +``` + +9. Now you can run Polykey as an agent with the following shell command + +```shell +docker run -it 0e1addd9855a agent start --background -np /tmp/polykey +``` + +Making sure to replace `0e1addd9855a` with your corresponding image ID. + +```shell + docker run -it 0e1addd9855a agent start --background -np /tmp/polykey +WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested +✔ Enter new password … * +✔ Confirm new password … * +pid 28 +nodeId vflhiouqt255gq22drpf0s639kl9eds3ralu094c6rsnmonemp6pg +clientHost 127.0.0.1 +clientPort 45509 +agentHost :: +agentPort 37468 +recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly whip simple warfare daughter pepper detail bachelor awkward forget ignore cream silly raw + +``` + + + + +## Node Package Manager + +The CLI is published as +[`npm` package](https://www.npmjs.com/package/polykey-cli). + +Install it with: + +```sh +npm install -g polykey-cli +``` + +This will install the Polykey-CLI into the path pointed to by the command +`$(npm config get prefix)`. + +If the `npm` bin path is added to the `$PATH` environment variable, then you +will be able to execute `pk` or `polykey`. + + + + +## Source + +The official source repository is on GitHub. There is an additional mirror on +GitLab. + +```shell +git clone https://github.com/MatrixAI/Polykey-CLI.git +``` + +Use `npm install` to setup the project. + +:::tip + +If you have `nix-shell` available, enter into `nix-shell` and it will +automatically setup the development environment. + +::: + + + + diff --git a/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md new file mode 100644 index 00000000..4adc59fb --- /dev/null +++ b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md @@ -0,0 +1,164 @@ +# Managing Multiple Local Nodes + +Managing multiple local + +nodes in Polykey can serve various purposes. For example, you might maintain one +node for personal projects and another for professional work. This segregation +ensures that the vaults and their respective contents remain distinct based on +their usage context. + +This approach is particularly advantageous for demonstrations or training +purposes, as it allows you to simulate sharing vaults between two nodes on the +network without requiring another live user. It also enables a robust +environment for testing node interactions and features in a controlled manner. + +Each node in Polykey operates with its own dedicated agent, and nodes are stored +locally with specified node paths. When you first initialize Polykey, a default +node and its path are created. This default node path can be viewed by running +specific Polykey commands, which we will cover. To manage multiple nodes +effectively, each node you create will have its designated node path that +directs all operations specifically to that node's environment. + +## Understanding Node Paths + +The default node, which you bootstrap when you first install Polykey, resides at +a standard location on your file system. This location can be found using: + +```bash +polykey nodes --help +``` + +For any additional nodes, such as nodeB, you will specify a new node path during +their creation. This is critical because each node operates independently, +requiring its unique path for all interactions: + +```bash +polykey agent start --node-path ./nodeB --background +``` + +This command initializes a Polykey agent using the nodePath flag to specify the +node we are starting an agent for. If unsure of the syntax to use for command +operations, adding the --help at the end of each subcommand provides useful +context. + +:::note If a node has not been created before, initializing the Polykey agent +for it will also initiate the bootstrap process. ::: + +When working with multiple nodes, specifying the node path in each command can +become cumbersome. To streamline this process in your terminal shell session, +you can set an environment variable for the node path, which we will demonstrate +later. + +## Steps to Manage Multiple Nodes Locally + +### 1. Initialize Your Nodes + +Open two terminal sessions (Shell A for your default node and Shell B for your +new node that we will save a new path called nodeB). If you have not already +started the Polykey agent for your default node, you can start it as follows: + +**Shell A (default node):** + +```bash +polykey agent start --background +``` + +This initializes your default node in the background. The command does not +specify a node path, so it automatically targets the default node path. + +**Shell B (for your new node, nodeB):** + +```bash +polykey agent super_start --node-path ./nodeB --background +``` + +This command starts a new Polykey agent for nodeB in the background. The first +time you run this, it will prompt you to set a password, just like bootstrapping +any new node. Remember, each node operates with its dedicated agent, ensuring +that their operations are isolated from each other. + +### 2. Configure Node Environment + +To avoid having to specify the node path for every command in a session: + +#### **Export the environment variable in Shell B:** + +```bash +export PK_NODE_PATH='./nodeB' +``` + +This sets the environment for nodeB in Shell B, allowing you to execute Polykey +commands specific to nodeB without constantly adding the node-path flag. + +### 3. Verify Node Status + +In both shell sessions, check that each node is active: + +```bash +polykey agent status +``` + +This command confirms the node's status and provides the nodeId, which is +crucial for the next steps. + +### 4. Node Discovery and Trust Establishment + +Before sharing any vaults, both nodes need to discover each other and establish +trust. Use the `nodeId` obtained from the status output: + +#### **Shell A (default node):** + +```bash +polykey identities discover +polykey identities trust +``` + +#### **Shell B (nodeB):** + +```bash +polykey identities discover +polykey identities trust +``` + +### 5. Share a Vault from the Default Node to nodeB + +Choose a vault to share, for example, `Weather-Ops`. + +#### **Shell A (default node):** + +```bash +polykey vaults share Weather-Ops +``` + +### 6. Access the Shared Vault from nodeB + +#### **Shell B (nodeB):** + +```bash +polykey vaults scan +polykey vaults clone Weather-Ops +``` + +These commands list and then clone the shared vault to nodeB's local storage. + +### 7. Validate the Operation + +Check that the vault is now available in nodeB: + +#### **Shell B (nodeB):** + +```bash +polykey vaults list +``` + +## Conclusion + +This tutorial demonstrated how to set up and manage multiple local nodes using +Polykey. You learned to initialize nodes, configure sessions, discover and trust +other nodes, share vaults, and access shared resources. Such a setup is +invaluable for developers managing separate environments for different projects +or testing functionality without another user. + +This approach not only streamlines the management of multiple nodes but also +ensures that all operations are performed securely and efficiently within +controlled environments. diff --git a/docs/Getting-Started/polykey-cli/managing-secrets.md b/docs/Getting-Started/polykey-cli/managing-secrets.md new file mode 100644 index 00000000..be040353 --- /dev/null +++ b/docs/Getting-Started/polykey-cli/managing-secrets.md @@ -0,0 +1,389 @@ +# Managing Secrets + +## Introduction + +Secrets in Polykey are essential for securely managing sensitive information, +such as API keys, configuration files, or documents. These can be any file type +that you need to encrypt and manage securely. This section provides a detailed +guide on how to manage these secrets within vaults using Polykey-CLI. + +:::tip + +In the Polykey CLI, you can get help with managing your Secrets Operations by +using the `-h` help command to get a detailed list of availiable options and +commands. Try running `polykey secrets -h` ::: + +## Creating Secrets + +:::note + +**Create a Secret within a given Vault** + +**Usage:** `polykey secrets create [options] ` + +**Arguments:** + +**directoryPath:** On disk path to the secret file with the contents of the new +secret. + +**secretPath:** Path to the secret to be created, + +specified as `:` ::: + +### Adding a Secret to a Vault + +The `polykey secrets create` command clones an existing file from your local +machine and stores it into an encrypted vault, creating a secret in the process. +Thus, providing secure data-at-rest encryption of the file. + +:::tip To create a secret, both the vault and file you are creating a secret +from, must already exist. Remember that to view the vaults contained within a +node, you run `$polykey vaults list`. This is useful for viewing the names of +the vaults you are trying to manage secrets with, as vaultName is one of the +command arguments that is commonly used. ::: + +#### Command Arguments + +```bash +polykey secrets create : +``` + + + +:::info The `` for the file you are trying to create a secret from can +either be a working directory filepath or a root path. Also notice that we +either have 1 space of seperation or a `:` between command arguments usually. +The angle braces are just being used in our explanation for specifying the +arguments more clearly. ::: + +#### Example Usage of `Polykey Secrets Create` + +```bash +polykey secrets create ./API_ACCESS_KEY.txt my-api-vault:API_ACCESS_KEY +``` + +This command cloned the `API_ACCESS_KEY.txt` file from the terminal's working +directory and saved it in a vault named `my-api-vault`, specifying the +secretName alias as `API_ACCESS_KEY`. We could have also provided the secretName +alias as `API.ACCESS_KEY.txt` but for most text files in Polykey, specifying the +file type extension is redundant. + +:::tip Since the secret or `` stored in the vault does not specify +the file type in its metadata, when you are storing binary files such as images +or videos, you may want to specify the file extension in the `secretName` alias +for better access & manageability. ::: + +## Listing Secrets + +:::note **List all Available Secrets for a Vault** + +**Usage:** `polykey secrets list|ls [options] ` + +**Arguments:** + +**vaultName:** Name of the vault to list secrets from + +::: + +To list the secret file(s) stored within a specific vault in your default +nodePath, use: + +#### Command Arguments: + +```bash +polykey secrets list +``` + +#### Example Usage + +```bash +Polykey secrets list my-api-vault +``` + +#### Example Output + +In this case, there's just one secret file contained in this vault, the secret +we created in the previous example. + +```bash +API_ACCESS_KEY +``` + +:::note + +### Secure Deletion of Local Secrets + +After adding a secret to a vault, securely delete the local copy if it's no +longer needed. This ensures that no unsecured traces of sensitive information +remain on your local filesystem. ::: + +## Retreiving Secrets + +Retrieve a secret from the given vault using the polykey secrets get command. +This command accesses the encrypted content within a vault and outputs it, +allowing for further handling depending on the file type. + +:::note + +Retrieve a Secret from the Given Vault + +**Usage:** `polykey secrets get [options] ` + +**Arguments:** + +**secretPath:** Path to where the secret to be retrieved, + +specified as `:` + +::: + +### Text and Binary File Handling + +The nature of the file affects how it is handled when retrieved: + +- **Text Files:** Files such as .txt, .cfg, or script files like .sh are + inherently text-based and can be displayed directly in the terminal. This + feature is useful for quick checks and edits directly from the command line. + +- **Binary Files:** Files like images, executables, or other non-text formats + are binary files. These do not display readable content directly in the + terminal and must be handled differently. + +### Retrieving a Text File + +To view the contents of a text file stored in a vault directly from the +terminal, use the following command: + +```bash +polykey secrets get : +``` + +#### Example: Retrieving a Text File + +Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault-tutorial-1` + +```bash +polykey secrets get my-vault-tutorial-1:API_ACCESS_KEY +``` + +#### Example Output + +```bash +AKfjd39jdi3903KDje93j04j0 +``` + +This method displays text files directly in the terminal, providing immediate +access to the contents. + +### Retrieving Binary File + +Binary files, such as images or executables, need to be handled appropriately to +view or use their contents correctly. + +#### Steps to Retrieve a Binary File + +To retrieve and handle a binary file, specify the output format by redirecting +the output to a file with the appropriate file extension: + +```bash +polykey secrets get : > . + +``` + +This command saves the binary content into a file in the current local +directory, preserving the file type as indicated by the extension ``. + +#### Example: Retrieving and Viewing an Image + +Retrieve an image stored in a vault and view it using system-specific commands: + +```bash +polykey secrets get my-NFT:Dali.png > Dali.png +open Dali.png +``` + +:::note The use of `>` in the command line is a standard Unix redirection +operator, used here to direct the output from Polykey into a file. This +operation is necessary for handling binary files that require specific +applications to open. ::: + +:::tip Ensure the secret name includes the file extension (like Dali.png), which +helps clarify the file type when saving and accessing the retrieved file. ::: + +## Creating a Directory of Secrets + +To create a directory within a vault, use the polykey secrets mkdir command. +This command allows you to organize your secrets into directories within a +vault. + +```bash +polykey secrets mkdir : +``` + +#### Example: Creating a Directory in a Vault + +To create a directory named "NFTs" within the "my-image-vault": + +```bash +polykey secrets mkdir my-image-vault:NFTs +``` + +### Adding a Secret to a Directory in a Vault + +After creating a directory, you can add secrets to it. This helps in organizing +similar types of secrets under a common directory. + +```bash +polykey secrets create :/ +``` + +#### Example: Adding a Secret to a Directory + +To add the file "Dali.png" as a secret named "Dali.png" to the "NFTs" directory +within "my-image-vault": + +```bash +polykey secrets create ./Dali.png my-image-vault:NFTs/Dali.png +``` + +:::note To view secrets saved within a directory in a vault, using the +`polykey secrets list ` command for that vault will output all +secrets in the vault, including those within directories. + +**Example Usage** + +```bash + polykey secrets list my-image-vault +``` + +**Output** + +```bash +NFTs/Owner.png +``` + +::: + +## Renaming a Secret + +To rename an existing secret: + +```bash +polykey secrets rename : +``` + +:::tip Use the `secrets list` command to check on your renamed secretFile. ::: + +## Updating a Secret + +To update the contents of an existing secret: + +```bash +polykey secrets update : +``` + +#### Example: Secrets Update + +```bash +polykey secrets update ./rare-dali.png my-image-vault:NFTs/Dali.png +``` + +:::info This is essentially replacing the file content of an existing secret +while preserving the identity of the secret. One way to verify that the update +was performed sucesfully is by viewing the mtime (modified time) timestamp from +the `secrets stat` command. ::: + +## Retrieving Secret Metadata + +To view metadata about a secret: + +```bash +polykey secrets stat : +``` + +#### Example: Viewing Metadata for a Secret + +```bash +polykey secrets stat my-image-vault:NFTs/Dali.png +``` + +#### Example Output + +```yaml +dev 0 ino 158 mode 33188 nlink 1 uid 0 gid 0 +rdev 0 size 23450 atime Sat May 25 2024 17:22:34 GMT-0600 +mtime Sat May 25 2024 17:22:33 GMT-0600 ctime Sat May 25 2024 17:22:33 +GMT-0600 birthtime Fri May 24 2024 22:42:43 GMT-0600 blksize 4096 blocks 6 +``` + +:::note + +### Understanding Metadata Terms + +- **dev:** Device number on which the file resides. +- **ino:** File's inode number. +- **mode:** File permission and type encoded in numeric format. +- **nlink:** Number of hard links. +- **uid:** User ID of file's owner. +- **gid:** Group ID of file's owner. +- **rdev:** Device ID (if special file). +- **size:** File size in bytes. +- **atime:** Last access timestamp. +- **mtime:** Last modification timestamp. +- **ctime:** Last status change timestamp. +- **birthtime:** Creation time of the file. +- **blksize:** Block size for filesystem I/O. +- **blocks:** Number of 512-byte blocks allocated. + +::: + +## Deleting Secrets + +To remove a secret from a vault: + +```bash +polykey secrets delete : +``` + +#### Example: Deleting a Secret + +```bash +polykey secrets list my-image-vault +``` + +**Output:** + +```bash +NFTs/Dali.png +THE_THIEF.png +``` + +```bash +polykey secrets delete my-image-vault:THE_THIEF.png +``` + +Successful deletion does not produce output. Verify the secret was removed by +listing secrets in the vault. + +```bash +polykey secrets list my-image vault +``` + +**Output:** + +Notice that we have sucesfully removed one of the secrets from the vault now. + +```bash +NFTs/Dali.png +``` + +## Editing Secrets in a Vault + +To edit a secret directly within a Vault using Polykey: + +```bash +polykey secrets edit : +``` + +:::warning Polykey Secrets Edit on Mac OS has a bug that we are investigating. +Use Polykey Secrets Update in the meantime. ::: diff --git a/docs/Getting-Started/polykey-cli/managing-vaults.md b/docs/Getting-Started/polykey-cli/managing-vaults.md new file mode 100644 index 00000000..f380be56 --- /dev/null +++ b/docs/Getting-Started/polykey-cli/managing-vaults.md @@ -0,0 +1,136 @@ +# Managing Vaults + +## Introduction + +Vaults in Polykey are secure containers where you can store and manage secrets +like passwords, tokens, certificates, and keys. Vaults are encrypted and only +accessible within your Polykey node. This section covers the basics of managing +vaults, including creating, listing, deleting, viewing vault history, and +renaming them. + +## Creating a Vault + +To create a new vault, use the following command: + +```bash +polykey vaults create +``` + +#### Example + +Create a new vault named `myvault`: + +```bash +polykey vaults create myvault +``` + +#### Example Output + +```bash +Vault zUvPxC9aKNw94E1yR9dffzY created successfully +``` + +## Listing Vaults + +To see all the vaults you have, use the list command. This provides a simple way +to view all vault names and their identifiers. + +```bash +polykey vaults list +``` + +#### Example Output + +```bash +my-software-project zD8XRJw2SoRoUW5e2mBR9tJ +myvault zD3cWJLBDEMWcbwNbjuUevo +myvault-101 zErezdpLocYs1VRZPV3wcqS +``` + +## Deleting a Vault + +If you need to remove a vault, you can delete it using the delete command: + +```bash +polykey vaults delete +``` + +#### Example + +Delete the vault named myvault: + +```bash +polykey vaults delete myvault +``` + +This operation does not produce output on successful execution, indicating the +vault has been removed. + +## Viewing Vault History + +Each vault maintains a version history which tracks changes over time. Use the +log command to view the history of commits to a vault. + +```bash +polykey vaults log +``` + +#### Example + +View the log for `my-software-project`: + +```bash +polykey vaults log my-software-project +``` + +#### Example Output + +```bash +commitId b568873376cd74a6c58755f73d1068cbb52cbc84 +committer vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg +timestamp Tue May 14 2024 21:27:52 GMT-0600 (Mountain Daylight Time) +message "AWS_SECRET_ACCESS_KEY added\n" +commitId 4d664db1f90f4c03d6c72be0fba4d3d1a3e7bda0 +committer vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg +timestamp Tue May 14 2024 21:27:43 GMT-0600 (Mountain Daylight Time) +message "AWS_ACCESS_KEY_ID added\n" +``` + +## Renaming a Vault + +To change the name of an existing vault, use the rename command. This allows you +to update the vault's name to something more descriptive or appropriate. + +```bash +polykey vaults rename +``` + +#### Example + +Rename `myvault-1` to `myvault-101`: + +```bash +polykey vaults rename myvault-1 myvault-101 +``` + +Confirm the rename by running: + +```bash +polykey vaults list +``` + +## Conclusion + +Managing vaults is a foundational skill in using Polykey effectively. This +section has guided you through the essential commands needed to create, manage, +and organize your vaults within Polykey. Further capabilities such as setting +permissions, sharing vaults, and pulling vaults from other nodes will be covered +in the Secrets Management section of our documentation. These basic +functionalities ensure that your secrets are well-organized and secure within +the network. + +For a full list of vault commands and options, run: + +```bash +polykey vaults -h +``` diff --git a/docs/Getting-Started/polykey-cli/sharing-vaults.md b/docs/Getting-Started/polykey-cli/sharing-vaults.md new file mode 100644 index 00000000..335a27bd --- /dev/null +++ b/docs/Getting-Started/polykey-cli/sharing-vaults.md @@ -0,0 +1,130 @@ +# Sharing Vaults With Secrets + +In Polykey, sharing vaults containing secrets is essential for collaborative +environments. This guide will walk you through the process of securely sharing +your vaults and enabling other users to access and synchronize secrets between +trusted nodes. + +## Prerequisites for Sharing Vaults + +Before sharing a vault, ensure that both nodes have established trust and +appropriate permissions are set. For details on setting trust and access +permissions, refer to the "Discovering Users' Nodes and Managing Access +Permissions" section. + +### Common Debugging Techniques for Sharing Secrets + +To share secrets between two nodes on different machines, both must be actively +connected to the Polykey network. Here are some techniques to ensure +connectivity and troubleshoot common issues: + +- **Node Ping:** Use `polykey nodes ping ` to check if the intended + recipient's node is active and reachable. + +- **Restarting Polykey Agent:** If connectivity issues persist, try restarting + the Polykey agent. Persistent errors might indicate restrictive network + settings blocking communication. + +- **Network Alternatives:** Connectivity issues may also be due to restrictive + networks, try connecting from a different network environment. + +- **Multiple Nodes:** To test sharing functionality without another user, set up + multiple nodes on your system. Refer to the managing multiple nodes section + for guidance. + +## Sharing the Vault + +Share a vault with another node using the `polykey vaults share` command: + +```bash +polykey vaults share +``` + +- ``: The name of the vault you wish to share. +- ``: The Node ID of the node you are sharing the vault with. + +:::tip + +Remember, you can run the following commands to reference the argument names to +pass into your command: + +- `polykey vaults list` +- `polykey identities list` + +::: + +### Example + +```bash +polykey vaults share my-software-project v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 +``` + +This command shares the "my-software-project" vault with the specified node. + +## Receiving a Shared Vault + +### Scanning for Available Vaults + +Once a vault is shared, the recipient should scan for available vaults: + +```bash +polykey vaults scan +``` + +- ``: The Node ID of the node that shared the vault with you. + +#### Example + +```bash +polykey vaults scan v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 +``` + +This command lists the vaults shared by the specified node. + +## Cloning the Shared Vault + +After identifying the shared vaults, the recipient can clone the desired vault +to their own local node: + +```bash +polykey vaults clone +``` + +- ``: The name of the vault to be cloned. +- ``: The Node ID from which to clone the vault. + +### Example + +```bash +polykey vaults clone myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 +``` + +This command clones "myvault" from the specified node to the local system. + +## Synchronizing Changes + +If updates are made to the original vault, such as key rotations or new secrets +added, the receiving node can synchronize these changes by pulling the latest +version of the vault: + +```bash +polykey vaults pull +``` + +- ``: The name or ID of the vault to update. +- ``: (Optional) The node ID from which to pull updates. + +### Example + +```bash +polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 +``` + +This command updates "myvault" with the latest changes from the specified node. + +## Conclussion + +Sharing and synchronizing vaults in Polykey enhances collaboration and security +across the network. By following these guidelines, users can effectively manage +sensitive data, ensuring all parties involved have secure and up-to-date access +to shared resources. diff --git a/docs/Getting-Started/polykey-cli/using-environment-variables.md b/docs/Getting-Started/polykey-cli/using-environment-variables.md new file mode 100644 index 00000000..536bc7d1 --- /dev/null +++ b/docs/Getting-Started/polykey-cli/using-environment-variables.md @@ -0,0 +1,171 @@ +# Using Environment Variables with Polykey + +Polykey revolutionizes the management of environment variables by injecting them +securely into applications, surpassing traditional `.env` file methods. This +tutorial delves into the capabilities of the `polykey secrets env` command, +illustrating its versatility and offering detailed usage examples. + +## Introduction + +Environment variables are essential for configuring applications outside the +codebase, managing sensitive data such as API keys and database connections. +Traditional `.env` file approaches expose these to risks such as accidental +exposure and plaintext storage vulnerabilities. Polykey addresses these issues +by storing environment variables in encrypted vaults and injecting them +dynamically into applications, enhancing security and usability. + +### Key Features of `polykey secrets env` + +- **Encrypted Storage:** Secrets are safely stored within encrypted vaults. +- **Dynamic Injection:** Direct injection of secrets into applications minimizes + exposure. +- **Decentralized Secure Sharing:** Supports encrypted secret sharing across + collaborative environments. +- **Cross-Platform Compatibility:** Adapts to different operating systems with + various output formats. + +## Prerequisites + +Before proceeding, ensure Polykey is installed on your system. Familiarize +yourself with creating vaults and managing secrets within Polykey. + +## Tutorial Structure + +This tutorial is structured to cover a range of scenarios illustrating the use +of the `polykey secrets env` command, ensuring you understand how to apply it +effectively across different contexts. + +## Use Cases and Examples + +### 1. Running Applications with Secure Environment Variables + +Inject secrets directly into your applications at runtime, the most common and +critical use case for the polykey secrets env command. + +#### Example: Start an application with a secure API key + +```bash +polykey secrets env --env Weather-Ops:API_KEY -- node app.js +``` + +This will execute `app.js` with the `API_KEY` set, sourced from the +`Weather-Ops` vault. + +### 2. Outputting Environment Variables + +When you need to verify or debug environment variables without executing an +application, you can output them in different formats. + +#### Unix-like Systems Example + +```bash +polykey secrets env --env-format unix --env Weather-Ops:API_KEY +``` + +#### JSON Format Example + +```bash +polykey secrets env --env-format json --env Weather-Ops:API_KEY +``` + +These commands display the environment variables in the console, useful for +validation. + +### 3. Managing Variable Name Conflicts + +Handle potential conflicts with invalid or duplicate environment variable names +efficiently. + +#### Ignore Invalid Names Example + +```bash +polykey secrets env --env-invalid ignore --env Weather-Ops:API_KEY -- node app.js +``` + +#### Overwrite Duplicates Example + +```bash +polykey secrets env --env-duplicate overwrite --env Weather-Ops:API_KEY -- node app.js +``` + +These settings help manage potential variable name issues dynamically during +runtime. + +### 4. Cloud Services Integration + +Showcase integrating with cloud services like AWS using securely managed +secrets. + +#### AWS CLI Integration Example + +```bash +polykey secrets env --env AWS-Creds:AWS_ACCESS_KEY_ID,AWS-Creds:AWS_SECRET_ACCESS_KEY -- aws s3 ls +``` + +This securely passes AWS credentials to the AWS CLI. + +## Managing Secrets Across Environments + +Discuss how to handle secrets in various environments such as development, +staging, and production, using different vaults or nodes. + +### Dynamic Environment Handling Example + +```bash +export PK_NODE_PATH='./prodNode' +polykey secrets env --env Production-Vault:SECRET_KEY -- node deploy.js +``` + +This facilitates secure management of different operational environments. + +## Conclusion + +The `polykey secrets env` command significantly enhances the security and +management of environment variables. It allows for the dynamic and secure +handling of sensitive data across different stages of development and +deployment. + +## Additional References + +We encourage you to delve deeper into Polykey and consider integrating it into +your workflows. For further insights and to participate in community +discussions, please explore the following resources: + +- [Demo on replacing dotenv libraries with `polykey secrets env`:](https://polykey.com/blog/introducing-polykey-a-future-security-standard-for-replacing-dotenv-libraries) + Discover how Polykey can replace traditional dotenv libraries to enhance your + project's security. +- [Using Polykey for secure access to cloud providers:](https://polykey.com/blog/introducing-a-new-standard-in-environment-secrets-management-with-polykey) + Learn how Polykey facilitates secure interactions with cloud services. + +## Tying It All Together + +**1. Initial Setup by User A:** + +- User A sets up a project repository utilizing environment variables stored in + a Polykey vault. + +**2. Collaboration with User B:** + +- User B, collaborating on the same project, requires access to the same + environment variables to maintain consistency and functionality. + +**3. Secure Sharing:** + +- User A shares the vault with User B securely through Polykey. Once User B + clones the vault, they can immediately use the custom script to inject the + necessary environment variables into their session, replicating User A’s setup + effortlessly. + +**4. Customization of Environment Variables:** + +- While some environment variables are shared, certain project-specific + variables may need to be adjusted. Both users can modify their respective + vaults or scripts as needed to accommodate these unique requirements. + +## Experiment with Polykey + +To see this process in action, consider following our detailed guide in the +dotenv library replacement demo. This demo provides hands-on experience with +simulating the secure environment variable sharing between two nodes controlled +by you, illustrating the practical benefits and ease of using Polykey in +collaborative environments. diff --git a/docs/Getting-Started/polykey-core/README.md b/docs/Getting-Started/polykey-core/README.md new file mode 100644 index 00000000..d218cebf --- /dev/null +++ b/docs/Getting-Started/polykey-core/README.md @@ -0,0 +1,5 @@ +import DocCardList from '@theme/DocCardList'; + +# Polykey Core + + diff --git a/docs/Getting-Started/polykey-core/installation.md b/docs/Getting-Started/polykey-core/installation.md new file mode 100644 index 00000000..6e898ecc --- /dev/null +++ b/docs/Getting-Started/polykey-core/installation.md @@ -0,0 +1,118 @@ +# Installation + +## Polykey Core + +The Polykey core contains the service, domain business logic and persistence +layers of Polykey. + +It is written in TypeScript and C++. + +The codebase is intended to be cross-platform, however it is currently only +tested on Linux. + +As a contributor, this would be your entrypoint to Polykey. + +:::caution + +At this point in time, the Polykey core library also contains all of the CLI +code. This means in order to use Polykey, you must use the Polykey core library. +We intend to extract out the CLI code, and move it into +[Polykey CLI](https://github.com/MatrixAI/Polykey-CLI). Once this is done, users +will not directly interact with the +[Polykey Core](https://github.com/MatrixAI/Polykey). Instead the core will just +be a dependency of the other projects. + +::: + +### Requirements + +- 64-bit Linux Operating System +- Node v16.15 or above and Node Package Manager +- Optionally `nix-shell` to setup development environment + +### Source Repository + +The official source repository is on GitHub. There is an additional mirror on +GitLab. + +```shell +git clone https://github.com/MatrixAI/Polykey.git +``` + +Use `npm install` to setup the project. + +:::tip + +If you have `nix-shell` available, enter into `nix-shell` and it will +automatically setup the develoment environment. + +::: + +### Node Package Manager + +The core library is published as +[`npm` package](https://www.npmjs.com/package/polykey). + +#### Global Package + +Install it with: + +```shell +npm install --location=global polykey +``` + +This will install the Polykey core library into `$(npm config get prefix)`. + +There will be 2 executables made available inside +`$(npm bin --location=global)`. + +For example on Ubuntu: + +```shell-session +$ tree "$(npm bin --location=global)" +/usr/local/bin/ +├── pk -> ../lib/node_modules/polykey/dist/bin/polykey.js +└── polykey -> ../lib/node_modules/polykey/dist/bin/polykey.js +``` + +If the `npm` bin path is added to the `$PATH` environment variable, then you +will be able to execute `pk` or `polykey`. + +#### Local Package + +Local installation is intended for downstream projects, where Polykey is +embedded as a JavaScript library. + +```shell +npm install polykey +``` + +Use the `npx polykey` or `npx pk` execute the local executables that are placed +in: + +```shell-session +$ tree ./node_modules/.bin +./node_modules/.bin/ +├── pk -> ../polykey/dist/bin/polykey.js +└── polykey -> ../polykey/dist/bin/polykey.js +``` + +### Bundled Executables + +The core library is also released as a bundled executable. This is intended for +users who do not have Node.js installed. + +Go to https://github.com/MatrixAI/Polykey/releases and download the relevant +asset. + +We currently bundle for these platforms: + +- linux-x64 - this should work for any Linux distribution that follows the + Filesystem Hierarchy Standard. +- win-x64 +- macos-x64 +- macos-arm64 + +:::caution + +Not all platfoms are supported currently. We have only tested on linux-x64. diff --git a/docs/README.md b/docs/README.md index 86d20745..a44de42e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,9 +7,6 @@ displayed_sidebar: docs Welcome to the Polykey documentation. -The documentation is structured using -[Divio system](https://documentation.divio.com/). - - [Tutorials](./tutorials) - these are a series of steps to introduce Polykey to new beginners to achieve a practical outcome - [How-To Guides](/docs/how-to-guides) - these are short guides on how to @@ -19,14 +16,12 @@ The documentation is structured using - [Reference](./reference/) - these are useful when you need remember how to use a particular command or function - - ## Introduction Polykey helps yourself, teams and software agents to manage and share secrets in a secure and easy-to-use manner. -- Usable for average humans, you don't need to be a cryptography or +- Usable for the average person, you don't need to be a cryptography or cybersecurity expert to securely manage and share secrets. - Can be integrated into software for automation of secret workflows. - Unifies the workflow between interactive password management and @@ -76,24 +71,24 @@ passwords or keys. For this reason, we think of secrets as "capabilities". -All secrets put into vaults. Each vault is a persistent fully-encrypted virtual +All secrets are put into vaults. Each vault is a persistent, fully encrypted virtual filesystem with automatic version history. Vaults can be shared with other Polykey agents. -Polykey's secrets management concept provides users with secure communication +Polykey's secrets management system provides users with secure communication and secure computation. ### Decentralized Trust -Sharing secrets depends secure communications. Secure communications depends on +Sharing secrets depends on secure communications. Secure communications depends on trusted identities. -Polykey introduced a concept called "Gestalt Identity". +Polykey introduces a concept called "Gestalt Identity". -A Gestalt Identity is a collection of digital identities (social media profiles +A Gestalt Identity is a collection of digital identities (i.e. social media profiles and Polykey nodes) that all represent the same entity. -When you start a Polykey agent, it immediate forms its own gestalt with the +When you start a Polykey agent, it immediately forms its own gestalt with the Polykey node as its only identity. Link up your digital identities to the node in order to expand your gestalt. diff --git a/sidebars.ts b/sidebars.ts index 1c9fb799..4a094ab0 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -4,7 +4,7 @@ const sidebars: SidebarsConfig = { docs: [ { type: 'category', - label: 'Tutorials', + label: 'Getting Started', collapsed: false, link: { type: 'doc', From 29818c164f0b73393faa0570b7f6fd36c5c7254b Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Thu, 10 Apr 2025 19:42:52 -1000 Subject: [PATCH 2/6] docs: update modified documentation files --- docs/Getting-Started/polykey-cli/README.md | 10 +- .../polykey-cli/bootstrapping.md | 38 ++++--- .../claiming-digital-identities.md | 26 +++-- .../polykey-cli/discovering-other-users.md | 17 +-- .../polykey-cli/installation.md | 18 ++- .../polykey-cli/managing-multiple-nodes.md | 13 ++- .../polykey-cli/managing-secrets.md | 107 ++++++++---------- .../polykey-cli/managing-vaults.md | 2 +- .../polykey-cli/sharing-vaults.md | 2 +- .../using-environment-variables.md | 2 +- 10 files changed, 123 insertions(+), 112 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/README.md b/docs/Getting-Started/polykey-cli/README.md index f2f6489b..1144884d 100644 --- a/docs/Getting-Started/polykey-cli/README.md +++ b/docs/Getting-Started/polykey-cli/README.md @@ -30,16 +30,20 @@ The CLI is open-source and available on GitHub: Polykey is continuously built and tested on: -- Linux x64 / arm64 +- Linux x64 - MacOS x64 / arm64 - Windows x64 - Docker -:::note Polykey is currently in beta. Its interface is at various levels of +:::note Note + + Polykey is currently in beta. Its interface is at various levels of stability. So bear with us as we perfect its design. You can contribute by discussing with us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue tickets in the -[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). ::: +[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). + +::: ## Getting Started diff --git a/docs/Getting-Started/polykey-cli/bootstrapping.md b/docs/Getting-Started/polykey-cli/bootstrapping.md index 44aeb7c8..e99e9a5d 100644 --- a/docs/Getting-Started/polykey-cli/bootstrapping.md +++ b/docs/Getting-Started/polykey-cli/bootstrapping.md @@ -24,8 +24,17 @@ encryption and decryption of all node state and secret data managed by Polykey. You will be prompted to provide a root password. This password encrypts the root key. -:::note Remember to keep your password in a secure location as you will need it -each time you start the Polykey agent. ::: +:::note Note + +Remember to keep your password in a secure location as you will need it each time you start the Polykey agent. + +::: + +:::important + +Bootstrapping also returns a **recovery code**. This code is required to recover a node with the same ID, so it is critical that you store it safely and securely. If lost, node identity recovery will not be possible. + +::: ### Starting the Polykey Agent @@ -64,7 +73,8 @@ If the Polykey agent does not terminate properly, you can force quit the process through the Activity Monitor on your machine. If you encounter this or any other issue, please consider making a [bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) to help -improve Polykey. +improve Polykey. Please make sure to check for existing issues before creating a +new one. ## Check Agent Status @@ -80,19 +90,19 @@ including its connectivity and activity within the network. ### Example Output ```bash -status LIVE -pid 96992 +sstatus LIVE +pid 20004 nodeId vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg -clientHost ::1 -clientPort 54975 +clientHost 127.0.0.1 +clientPort 51980 agentHost :: -agentPort 60358 -upTime 8 -startTime 1716509093 -connectionsActive 3 -nodesTotal 11 -version 1.2.3-alpha.4-1-1 -sourceVersion 1.2.3-alpha.4 +agentPort 58078 +upTime 120 +startTime 1742186927 +connectionsActive 0 +nodesTotal 2 +version 1.21.4-1-1 +sourceVersion 1.21.4 stateVersion 1 networkVersion 1 ``` diff --git a/docs/Getting-Started/polykey-cli/claiming-digital-identities.md b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md index 3a093a1c..f84762bd 100644 --- a/docs/Getting-Started/polykey-cli/claiming-digital-identities.md +++ b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md @@ -1,4 +1,4 @@ -# Claiming Digital Identities: Establishing Identity Linkages in Polykey +# Establishing Identity Linkages in Polykey In Polykey, claiming a digital identity is a crucial step that allows users to establish their identity across various platforms and link these identities to @@ -8,7 +8,7 @@ cryptographic link to a publicly verifiable location. This tutorial will guide you through the steps to authenticate with GitHub and claim an identity using Polykey, enhancing security and streamlining identity -verification, making it easier for other users to discover and trust your nodes. +verification, making it easier for other users to discover and trust your nodes. Currently, we only support github as an identity provider, but we plan to add more in the future. ## Step 1: Authenticate with GitHub @@ -31,7 +31,9 @@ polykey identities authenticate ``: The identifier for the digital identity provider, such as "github". ::: -:::note Since Polykey currently only supports GitHub as an IdP, this is the +:::note Note + +Since Polykey currently only supports GitHub as an IdP, this is the command that you will use to start the authentication process. ```bash @@ -72,19 +74,19 @@ identityId maverick During the authentication process, here's what Polykey requests access to and why: -- **Create Gists:** Polykey creates a gist under your GitHub account containing +- **Currently: Create Gists:** Polykey creates a gist under your GitHub account containing a cryptographic link. This link is a verifiable method that proves the ownership of your GitHub identity to anyone checking your Polykey gestalt graph. -- **Read All User Profile Data:** This enables Polykey to access your profile +-:::note Note + + **Future Plan: Read All User Profile Data:** This enables Polykey to access your profile details, including your username, followers, and public repository data. This information is used to ensure that the identity you claim corresponds accurately to your public digital footprint, enhancing trust and verification. -- **Access User Email Addresses (read-only):** By accessing the email addresses - associated with your account, Polykey can better manage notifications related - to your secrets operations. + ::: #### Security and Privacy Considerations @@ -148,7 +150,13 @@ https://gist.github.com/my-github-username This gist contains the cryptographic link confirming that your Polykey identity is correctly linked to your GitHub profile. Viewing this gist ensures your claim -was successful and publicly verifiable. +was successful and publicly verifiable. + +:::note Note + +This information should not be modified or the claim might be invalidated. + +::: ## Understanding Gestalt Graphs diff --git a/docs/Getting-Started/polykey-cli/discovering-other-users.md b/docs/Getting-Started/polykey-cli/discovering-other-users.md index abccd71d..15e6d6d5 100644 --- a/docs/Getting-Started/polykey-cli/discovering-other-users.md +++ b/docs/Getting-Started/polykey-cli/discovering-other-users.md @@ -38,10 +38,11 @@ polykey identities discover ```bash polykey identities discover github.com:maverick ``` - +:::note Note This command adds the node associated with the GitHub username "maverick" to your discovery queue, allowing you to initiate interactions with this user. -:::note + +::: ## Troubleshooting Discovery and Connection Issues @@ -77,8 +78,6 @@ network. ::: -:::info - ### Future Enhancements Polykey is actively working to enhance the discovery process by implementing @@ -116,13 +115,9 @@ Permissions in Polykey determine what actions a node or an identity can perform within the network. Here’s a general list of potential permissions that can be managed: -- **Read:** Allows viewing but not modifying. -- **Write:** Allows both viewing and modifying. -- **Execute:** Allows performing specific actions. +- **Scan:** Allows the node to scan for vaults - **Notify:** Allows sending notifications about changes or updates. -- **Trust:** Allows a node to be trusted, generally affecting how interactions - are secured. - +- **Claim** Allows a different gstalt to claim the node #### Example Command to Set Permissions ```bash @@ -197,7 +192,7 @@ polykey identities list ### Trusting and Untrusting Nodes -You can explicitly trust or untrust a node to refine how notifications and +You can explicitly trust or untrust individual nodes or entire gestalts to refine how notifications and access controls are handled: ```bash diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index adf69156..3263a429 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -126,13 +126,13 @@ $ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$( We will be working on other distribution methods. - + ## MacOS :::info -ARM-64 builds are not currently supported on MacOS as of **26-03-24.** However, +ARM-64 builds are not currently supported on MacOS as of **6 April 2025.** However, building Polykey yourself on MacOS resolves in a working binary. Follow this guide below to manually build and install Polykey on macOS. @@ -284,13 +284,21 @@ echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc +:::tip + +The path export should not pint to the Polykey executable itself, but rather to +the directory containing the executable. Otherwise, the executable will not be +found and will not work. + +::: + #### For Bash: 1. `cd` into the directory where the "polykey" executable is stored. 2. Edit the Bash config to add "polykey" to your path. To streamline the process, run the following command, making sure to change the path to "polykey" if the executable is not in the downloads folder. For most users, - this would be `~/downloads` on Debian-based systems. + this would be `~/Downloads` :::tip @@ -408,7 +416,7 @@ docker run -it 0e1addd9855a agent start --background -np /tmp/polykey Making sure to replace `0e1addd9855a` with your corresponding image ID. ```shell - docker run -it 0e1addd9855a agent start --background -np /tmp/polykey +$ docker run -it 0e1addd9855a agent start --background -np /tmp/polykey WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested ✔ Enter new password … * ✔ Confirm new password … * @@ -418,7 +426,7 @@ clientHost 127.0.0.1 clientPort 45509 agentHost :: agentPort 37468 -recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly whip simple warfare daughter pepper detail bachelor awkward forget ignore cream silly raw +recoveryCode (random text recovery code goes here) ``` diff --git a/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md index 4adc59fb..bb011a27 100644 --- a/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md +++ b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md @@ -2,10 +2,7 @@ Managing multiple local -nodes in Polykey can serve various purposes. For example, you might maintain one -node for personal projects and another for professional work. This segregation -ensures that the vaults and their respective contents remain distinct based on -their usage context. +nodes in Polykey can serve various purposes. For example, you might maintain one node for personal projects and another for professional work. This segregation ensures that the vaults and their respective contents remain distinct based on their usage context. This approach is particularly advantageous for demonstrations or training purposes, as it allows you to simulate sharing vaults between two nodes on the @@ -41,8 +38,12 @@ node we are starting an agent for. If unsure of the syntax to use for command operations, adding the --help at the end of each subcommand provides useful context. -:::note If a node has not been created before, initializing the Polykey agent -for it will also initiate the bootstrap process. ::: +:::note Note + + If a node has not been created before, initializing the Polykey agent +for it will also initiate the bootstrap process. + +::: When working with multiple nodes, specifying the node path in each command can become cumbersome. To streamline this process in your terminal shell session, diff --git a/docs/Getting-Started/polykey-cli/managing-secrets.md b/docs/Getting-Started/polykey-cli/managing-secrets.md index be040353..593bb15e 100644 --- a/docs/Getting-Started/polykey-cli/managing-secrets.md +++ b/docs/Getting-Started/polykey-cli/managing-secrets.md @@ -10,12 +10,12 @@ guide on how to manage these secrets within vaults using Polykey-CLI. :::tip In the Polykey CLI, you can get help with managing your Secrets Operations by -using the `-h` help command to get a detailed list of availiable options and -commands. Try running `polykey secrets -h` ::: +using the `-help` help command to get a detailed list of availiable options and +commands. Try running `polykey secrets -help` ::: ## Creating Secrets -:::note +:::note Note **Create a Secret within a given Vault** @@ -28,7 +28,9 @@ secret. **secretPath:** Path to the secret to be created, -specified as `:` ::: +specified as `:` + + ::: ### Adding a Secret to a Vault @@ -38,7 +40,7 @@ Thus, providing secure data-at-rest encryption of the file. :::tip To create a secret, both the vault and file you are creating a secret from, must already exist. Remember that to view the vaults contained within a -node, you run `$polykey vaults list`. This is useful for viewing the names of +node, you run `polykey vaults list`. This is useful for viewing the names of the vaults you are trying to manage secrets with, as vaultName is one of the command arguments that is commonly used. ::: @@ -48,15 +50,15 @@ command arguments that is commonly used. ::: polykey secrets create : ``` - +:::info -:::info The `` for the file you are trying to create a secret from can +The `` for the file you are trying to create a secret from can either be a working directory filepath or a root path. Also notice that we either have 1 space of seperation or a `:` between command arguments usually. -The angle braces are just being used in our explanation for specifying the -arguments more clearly. ::: -#### Example Usage of `Polykey Secrets Create` +::: + +#### Example Usage of `polykey secrets create` ```bash polykey secrets create ./API_ACCESS_KEY.txt my-api-vault:API_ACCESS_KEY @@ -155,20 +157,15 @@ To view the contents of a text file stored in a vault directly from the terminal, use the following command: ```bash -polykey secrets get : +polykey secrets cat : ``` #### Example: Retrieving a Text File -Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault-tutorial-1` +Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault` -```bash -polykey secrets get my-vault-tutorial-1:API_ACCESS_KEY -``` - -#### Example Output - -```bash +```shell +$ polykey secrets cat my-vault:API_ACCESS_KEY AKfjd39jdi3903KDje93j04j0 ``` @@ -198,17 +195,25 @@ directory, preserving the file type as indicated by the extension ``. Retrieve an image stored in a vault and view it using system-specific commands: ```bash -polykey secrets get my-NFT:Dali.png > Dali.png -open Dali.png +$polykey secrets get my-NFT:Dali.png > Dali.png +$open Dali.png ``` -:::note The use of `>` in the command line is a standard Unix redirection +:::note Note + +The use of `>` in the command line is a standard Unix redirection operator, used here to direct the output from Polykey into a file. This operation is necessary for handling binary files that require specific -applications to open. ::: +applications to open. + +::: + +:::tip Tip -:::tip Ensure the secret name includes the file extension (like Dali.png), which -helps clarify the file type when saving and accessing the retrieved file. ::: +Ensure the secret name includes the file extension (like Dali.png), which +helps clarify the file type when saving and accessing the retrieved file. + +::: ## Creating a Directory of Secrets @@ -274,18 +279,18 @@ polykey secrets rename : :::tip Use the `secrets list` command to check on your renamed secretFile. ::: -## Updating a Secret +### Updating a Secret To update the contents of an existing secret: ```bash -polykey secrets update : +polykey secrets write : ``` #### Example: Secrets Update ```bash -polykey secrets update ./rare-dali.png my-image-vault:NFTs/Dali.png +$ cat ./rare-dali.png | polykey secrets write my-image-vault:nfts/dali.png ``` :::info This is essentially replacing the file content of an existing secret @@ -309,11 +314,11 @@ polykey secrets stat my-image-vault:NFTs/Dali.png #### Example Output -```yaml -dev 0 ino 158 mode 33188 nlink 1 uid 0 gid 0 -rdev 0 size 23450 atime Sat May 25 2024 17:22:34 GMT-0600 -mtime Sat May 25 2024 17:22:33 GMT-0600 ctime Sat May 25 2024 17:22:33 -GMT-0600 birthtime Fri May 24 2024 22:42:43 GMT-0600 blksize 4096 blocks 6 +```bash +-> polykey nodes connections +host hostname nodeIdEncoded port timeout usageCount authenticated +13.210.66.119 N/A v8k5smi8a5o7j4mhdka50q679op9lctdcepgkuslrhumc0ur793og 1314 34004 0 false +2600:1f16:1f71:7c00:3593:3a22:674f:f33b N/A vair3u8kqfqoheulk277bp71j5vi80vd2bnavki02ekeounp72e80 1314 55884 0 false ``` :::note @@ -342,40 +347,20 @@ GMT-0600 birthtime Fri May 24 2024 22:42:43 GMT-0600 blksize 4096 blocks 6 To remove a secret from a vault: ```bash -polykey secrets delete : +polykey secrets rm : ``` #### Example: Deleting a Secret -```bash -polykey secrets list my-image-vault -``` +$ polykey secrets ls my-image-vault:nfts +nfts/dali.png +nfts/some-image.png -**Output:** - -```bash -NFTs/Dali.png -THE_THIEF.png -``` - -```bash -polykey secrets delete my-image-vault:THE_THIEF.png -``` +$ polykey secrets rm my-image-vault:nfts/some-image.png +# note the lack of output -Successful deletion does not produce output. Verify the secret was removed by -listing secrets in the vault. - -```bash -polykey secrets list my-image vault -``` - -**Output:** - -Notice that we have sucesfully removed one of the secrets from the vault now. - -```bash -NFTs/Dali.png -``` +$ polykey secrets ls my-image-vault:nfts +nfts/dali.png ## Editing Secrets in a Vault diff --git a/docs/Getting-Started/polykey-cli/managing-vaults.md b/docs/Getting-Started/polykey-cli/managing-vaults.md index f380be56..152fb8cb 100644 --- a/docs/Getting-Started/polykey-cli/managing-vaults.md +++ b/docs/Getting-Started/polykey-cli/managing-vaults.md @@ -60,7 +60,7 @@ polykey vaults delete Delete the vault named myvault: ```bash -polykey vaults delete myvault +polykey vaults rm myvault ``` This operation does not produce output on successful execution, indicating the diff --git a/docs/Getting-Started/polykey-cli/sharing-vaults.md b/docs/Getting-Started/polykey-cli/sharing-vaults.md index 335a27bd..ad3742d6 100644 --- a/docs/Getting-Started/polykey-cli/sharing-vaults.md +++ b/docs/Getting-Started/polykey-cli/sharing-vaults.md @@ -122,7 +122,7 @@ polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv50 This command updates "myvault" with the latest changes from the specified node. -## Conclussion +## Conclusion Sharing and synchronizing vaults in Polykey enhances collaboration and security across the network. By following these guidelines, users can effectively manage diff --git a/docs/Getting-Started/polykey-cli/using-environment-variables.md b/docs/Getting-Started/polykey-cli/using-environment-variables.md index 536bc7d1..501bb1e2 100644 --- a/docs/Getting-Started/polykey-cli/using-environment-variables.md +++ b/docs/Getting-Started/polykey-cli/using-environment-variables.md @@ -45,7 +45,7 @@ critical use case for the polykey secrets env command. #### Example: Start an application with a secure API key ```bash -polykey secrets env --env Weather-Ops:API_KEY -- node app.js +polykey secrets env weather-ops:API_KEY -- node app.js ``` This will execute `app.js` with the `API_KEY` set, sourced from the From a74eae6bec23e6ab562a064965b499e3edd21a65 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 13 Apr 2025 12:54:25 -1000 Subject: [PATCH 3/6] docs: update installation and env variable docs for Polykey CLI refresh --- docs/Getting-Started/polykey-cli/installation.md | 4 +++- .../polykey-cli/using-environment-variables.md | 13 ++++++++++--- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 3263a429..8b96e4fb 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -6,7 +6,9 @@ Installing the CLI can be done in different ways depending on your operating environment. :::info +## Polykey Core Overview +The Polykey CLI and core primarily use TypeScript for service logic, domain business operations, and persistence layers. While the main codebase is in TypeScript, some supporting libraries incorporate native C++ or Rust for platform‐specific functionality. This approach combines cross‐platform convenience with native performance optimizations. Polykey-CLI has only been tested on Linux and macOS. We are working on supporting other platforms. There's minor teething problems when it comes supporting other platforms. Help us by reporting any issues with the CLI tool in @@ -441,7 +443,7 @@ The CLI is published as Install it with: ```sh -npm install -g polykey-cli +npm install polykey ``` This will install the Polykey-CLI into the path pointed to by the command diff --git a/docs/Getting-Started/polykey-cli/using-environment-variables.md b/docs/Getting-Started/polykey-cli/using-environment-variables.md index 501bb1e2..73f20e9c 100644 --- a/docs/Getting-Started/polykey-cli/using-environment-variables.md +++ b/docs/Getting-Started/polykey-cli/using-environment-variables.md @@ -59,13 +59,19 @@ application, you can output them in different formats. #### Unix-like Systems Example ```bash -polykey secrets env --env-format unix --env Weather-Ops:API_KEY +olykey secrets env --env-format unix --env MyVault:API_KEY + +API_KEY=someRandomValue123 ``` #### JSON Format Example ```bash -polykey secrets env --env-format json --env Weather-Ops:API_KEY +polykey secrets env --env-format json --env MyVault:API_KEY + +{ + "API_KEY": "someRandomValue123" +} ``` These commands display the environment variables in the console, useful for @@ -99,7 +105,8 @@ secrets. #### AWS CLI Integration Example ```bash -polykey secrets env --env AWS-Creds:AWS_ACCESS_KEY_ID,AWS-Creds:AWS_SECRET_ACCESS_KEY -- aws s3 ls +polykey secrets env \ + $ polykey secrets env aws-creds:AWS_ACCESS_KEY_ID aws-creds:AWS_SECRET_ACCESS_KEY -- aws s3 ls ``` This securely passes AWS credentials to the AWS CLI. From 85cc359b2ee5e14a282ccdb515c4dfab59040558 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 13 Apr 2025 13:17:06 -1000 Subject: [PATCH 4/6] docs: update sidebar paths to match new Getting-Started structure --- sidebars.ts | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/sidebars.ts b/sidebars.ts index 4a094ab0..8cceea87 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -19,15 +19,15 @@ const sidebars: SidebarsConfig = { id: 'tutorials/polykey-cli/README', }, items: [ - 'tutorials/polykey-cli/installation', - 'tutorials/polykey-cli/bootstrapping', - 'tutorials/polykey-cli/managing-vaults', - 'tutorials/polykey-cli/managing-secrets', - 'tutorials/polykey-cli/claiming-digital-identities', - 'tutorials/polykey-cli/discovering-other-users', - 'tutorials/polykey-cli/sharing-vaults', - 'tutorials/polykey-cli/managing-multiple-nodes', - 'tutorials/polykey-cli/using-environment-variables', + 'Getting-Started/polykey-cli/installation', + 'Getting-Started/polykey-cli/bootstrapping', + 'Getting-Started/polykey-cli/managing-vaults', + 'Getting-Started/polykey-cli/managing-secrets', + 'Getting-Started/polykey-cli/claiming-digital-identities', + 'Getting-Started/polykey-cli/discovering-other-users', + 'Getting-Started/polykey-cli/sharing-vaults', + 'Getting-Started/polykey-cli/managing-multiple-nodes', + 'Getting-Started/polykey-cli/using-environment-variables', ], }, { From 480149ffcaa151e8d831a88f9082aa173cb14f76 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 13 Apr 2025 15:11:32 -1000 Subject: [PATCH 5/6] docs: update documentation changes docs: updated source control docs: fixed formatting docs: removed irrelevant files fix: build --- docs/Getting-Started/polykey-cli/README.md | 8 +- .../polykey-cli/managing-multiple-nodes.md | 2 +- .../polykey-cli/managing-secrets.md | 23 +- .../polykey-cli/managing-vaults.md | 3 +- .../polykey-cli/sharing-vaults.md | 12 +- .../using-environment-variables.md | 4 +- docs/Getting-Started/polykey-core/README.md | 5 - .../polykey-core/installation.md | 118 ----- .../reference/polykey-cli/commands/secrets.md | 31 +- docs/tutorials/README.md | 11 - docs/tutorials/polykey-cli/README.md | 81 --- docs/tutorials/polykey-cli/bootstrapping.md | 151 ------ .../claiming-digital-identities.md | 217 -------- .../polykey-cli/discovering-other-users.md | 220 -------- docs/tutorials/polykey-cli/installation.md | 468 ------------------ .../polykey-cli/managing-multiple-nodes.md | 164 ------ .../tutorials/polykey-cli/managing-secrets.md | 389 --------------- docs/tutorials/polykey-cli/managing-vaults.md | 136 ----- docs/tutorials/polykey-cli/sharing-vaults.md | 130 ----- .../using-environment-variables.md | 171 ------- docs/tutorials/polykey-core/README.md | 5 - docs/tutorials/polykey-core/installation.md | 118 ----- docs/tutorials/polykey-desktop/README.md | 12 - docs/tutorials/polykey-mobile/README.md | 12 - sidebars.ts | 35 +- 25 files changed, 61 insertions(+), 2465 deletions(-) delete mode 100644 docs/Getting-Started/polykey-core/README.md delete mode 100644 docs/Getting-Started/polykey-core/installation.md delete mode 100644 docs/tutorials/README.md delete mode 100644 docs/tutorials/polykey-cli/README.md delete mode 100644 docs/tutorials/polykey-cli/bootstrapping.md delete mode 100644 docs/tutorials/polykey-cli/claiming-digital-identities.md delete mode 100644 docs/tutorials/polykey-cli/discovering-other-users.md delete mode 100644 docs/tutorials/polykey-cli/installation.md delete mode 100644 docs/tutorials/polykey-cli/managing-multiple-nodes.md delete mode 100644 docs/tutorials/polykey-cli/managing-secrets.md delete mode 100644 docs/tutorials/polykey-cli/managing-vaults.md delete mode 100644 docs/tutorials/polykey-cli/sharing-vaults.md delete mode 100644 docs/tutorials/polykey-cli/using-environment-variables.md delete mode 100644 docs/tutorials/polykey-core/README.md delete mode 100644 docs/tutorials/polykey-core/installation.md delete mode 100644 docs/tutorials/polykey-desktop/README.md delete mode 100644 docs/tutorials/polykey-mobile/README.md diff --git a/docs/Getting-Started/polykey-cli/README.md b/docs/Getting-Started/polykey-cli/README.md index 1144884d..eb1d32ba 100644 --- a/docs/Getting-Started/polykey-cli/README.md +++ b/docs/Getting-Started/polykey-cli/README.md @@ -49,9 +49,13 @@ tickets in the Start your journey with Polykey by following the tutorials below in sequence: -:::tip For a visual walkthrough, check out our +:::tip Tip + +For a visual walkthrough, check out our [getting started demo video](https://vimeo.com/884649667) after installing -Polykey. ::: +Polykey. + +::: 1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install Polykey CLI on your platform. diff --git a/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md index bb011a27..36c537c4 100644 --- a/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md +++ b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md @@ -70,7 +70,7 @@ specify a node path, so it automatically targets the default node path. **Shell B (for your new node, nodeB):** ```bash -polykey agent super_start --node-path ./nodeB --background +polykey agent start --node-path ./nodeB --background ``` This command starts a new Polykey agent for nodeB in the background. The first diff --git a/docs/Getting-Started/polykey-cli/managing-secrets.md b/docs/Getting-Started/polykey-cli/managing-secrets.md index 593bb15e..26712b73 100644 --- a/docs/Getting-Started/polykey-cli/managing-secrets.md +++ b/docs/Getting-Started/polykey-cli/managing-secrets.md @@ -111,15 +111,13 @@ we created in the previous example. API_ACCESS_KEY ``` -:::note - -### Secure Deletion of Local Secrets +:::note Secure Deletion of Local Secrets After adding a secret to a vault, securely delete the local copy if it's no longer needed. This ensures that no unsecured traces of sensitive information remain on your local filesystem. ::: -## Retreiving Secrets + Retreiving Secrets Retrieve a secret from the given vault using the polykey secrets get command. This command accesses the encrypted content within a vault and outputs it, @@ -225,13 +223,14 @@ vault. polykey secrets mkdir : ``` -#### Example: Creating a Directory in a Vault +:::note Example: Creating a Directory in a Vault To create a directory named "NFTs" within the "my-image-vault": ```bash polykey secrets mkdir my-image-vault:NFTs ``` +:::note ### Adding a Secret to a Directory in a Vault @@ -306,14 +305,14 @@ To view metadata about a secret: polykey secrets stat : ``` -#### Example: Viewing Metadata for a Secret +:::note Note + +Example: Viewing Metadata for a Secret ```bash polykey secrets stat my-image-vault:NFTs/Dali.png ``` -#### Example Output - ```bash -> polykey nodes connections host hostname nodeIdEncoded port timeout usageCount authenticated @@ -350,14 +349,18 @@ To remove a secret from a vault: polykey secrets rm : ``` -#### Example: Deleting a Secret +:::note Note + Example: Deleting a Secret $ polykey secrets ls my-image-vault:nfts nfts/dali.png nfts/some-image.png $ polykey secrets rm my-image-vault:nfts/some-image.png -# note the lack of output + +Note the lack of output + +:::note $ polykey secrets ls my-image-vault:nfts nfts/dali.png diff --git a/docs/Getting-Started/polykey-cli/managing-vaults.md b/docs/Getting-Started/polykey-cli/managing-vaults.md index 152fb8cb..8f412ba7 100644 --- a/docs/Getting-Started/polykey-cli/managing-vaults.md +++ b/docs/Getting-Started/polykey-cli/managing-vaults.md @@ -55,7 +55,7 @@ If you need to remove a vault, you can delete it using the delete command: polykey vaults delete ``` -#### Example +:::note Example Delete the vault named myvault: @@ -66,6 +66,7 @@ polykey vaults rm myvault This operation does not produce output on successful execution, indicating the vault has been removed. +:::note ## Viewing Vault History Each vault maintains a version history which tracks changes over time. Use the diff --git a/docs/Getting-Started/polykey-cli/sharing-vaults.md b/docs/Getting-Started/polykey-cli/sharing-vaults.md index ad3742d6..224cb234 100644 --- a/docs/Getting-Started/polykey-cli/sharing-vaults.md +++ b/docs/Getting-Started/polykey-cli/sharing-vaults.md @@ -73,7 +73,7 @@ polykey vaults scan - ``: The Node ID of the node that shared the vault with you. -#### Example +:::note Example ```bash polykey vaults scan v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 @@ -81,6 +81,8 @@ polykey vaults scan v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 This command lists the vaults shared by the specified node. +:::note + ## Cloning the Shared Vault After identifying the shared vaults, the recipient can clone the desired vault @@ -93,12 +95,14 @@ polykey vaults clone - ``: The name of the vault to be cloned. - ``: The Node ID from which to clone the vault. -### Example +:::note Example ```bash polykey vaults clone myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 ``` +:::note + This command clones "myvault" from the specified node to the local system. ## Synchronizing Changes @@ -114,7 +118,7 @@ polykey vaults pull - ``: The name or ID of the vault to update. - ``: (Optional) The node ID from which to pull updates. -### Example +:::note Example ```bash polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 @@ -122,6 +126,8 @@ polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv50 This command updates "myvault" with the latest changes from the specified node. +:::note + ## Conclusion Sharing and synchronizing vaults in Polykey enhances collaboration and security diff --git a/docs/Getting-Started/polykey-cli/using-environment-variables.md b/docs/Getting-Started/polykey-cli/using-environment-variables.md index 73f20e9c..e055a10f 100644 --- a/docs/Getting-Started/polykey-cli/using-environment-variables.md +++ b/docs/Getting-Started/polykey-cli/using-environment-variables.md @@ -132,7 +132,7 @@ management of environment variables. It allows for the dynamic and secure handling of sensitive data across different stages of development and deployment. -## Additional References +:::note Additional References We encourage you to delve deeper into Polykey and consider integrating it into your workflows. For further insights and to participate in community @@ -144,6 +144,8 @@ discussions, please explore the following resources: - [Using Polykey for secure access to cloud providers:](https://polykey.com/blog/introducing-a-new-standard-in-environment-secrets-management-with-polykey) Learn how Polykey facilitates secure interactions with cloud services. +:::note + ## Tying It All Together **1. Initial Setup by User A:** diff --git a/docs/Getting-Started/polykey-core/README.md b/docs/Getting-Started/polykey-core/README.md deleted file mode 100644 index d218cebf..00000000 --- a/docs/Getting-Started/polykey-core/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Core - - diff --git a/docs/Getting-Started/polykey-core/installation.md b/docs/Getting-Started/polykey-core/installation.md deleted file mode 100644 index 6e898ecc..00000000 --- a/docs/Getting-Started/polykey-core/installation.md +++ /dev/null @@ -1,118 +0,0 @@ -# Installation - -## Polykey Core - -The Polykey core contains the service, domain business logic and persistence -layers of Polykey. - -It is written in TypeScript and C++. - -The codebase is intended to be cross-platform, however it is currently only -tested on Linux. - -As a contributor, this would be your entrypoint to Polykey. - -:::caution - -At this point in time, the Polykey core library also contains all of the CLI -code. This means in order to use Polykey, you must use the Polykey core library. -We intend to extract out the CLI code, and move it into -[Polykey CLI](https://github.com/MatrixAI/Polykey-CLI). Once this is done, users -will not directly interact with the -[Polykey Core](https://github.com/MatrixAI/Polykey). Instead the core will just -be a dependency of the other projects. - -::: - -### Requirements - -- 64-bit Linux Operating System -- Node v16.15 or above and Node Package Manager -- Optionally `nix-shell` to setup development environment - -### Source Repository - -The official source repository is on GitHub. There is an additional mirror on -GitLab. - -```shell -git clone https://github.com/MatrixAI/Polykey.git -``` - -Use `npm install` to setup the project. - -:::tip - -If you have `nix-shell` available, enter into `nix-shell` and it will -automatically setup the develoment environment. - -::: - -### Node Package Manager - -The core library is published as -[`npm` package](https://www.npmjs.com/package/polykey). - -#### Global Package - -Install it with: - -```shell -npm install --location=global polykey -``` - -This will install the Polykey core library into `$(npm config get prefix)`. - -There will be 2 executables made available inside -`$(npm bin --location=global)`. - -For example on Ubuntu: - -```shell-session -$ tree "$(npm bin --location=global)" -/usr/local/bin/ -├── pk -> ../lib/node_modules/polykey/dist/bin/polykey.js -└── polykey -> ../lib/node_modules/polykey/dist/bin/polykey.js -``` - -If the `npm` bin path is added to the `$PATH` environment variable, then you -will be able to execute `pk` or `polykey`. - -#### Local Package - -Local installation is intended for downstream projects, where Polykey is -embedded as a JavaScript library. - -```shell -npm install polykey -``` - -Use the `npx polykey` or `npx pk` execute the local executables that are placed -in: - -```shell-session -$ tree ./node_modules/.bin -./node_modules/.bin/ -├── pk -> ../polykey/dist/bin/polykey.js -└── polykey -> ../polykey/dist/bin/polykey.js -``` - -### Bundled Executables - -The core library is also released as a bundled executable. This is intended for -users who do not have Node.js installed. - -Go to https://github.com/MatrixAI/Polykey/releases and download the relevant -asset. - -We currently bundle for these platforms: - -- linux-x64 - this should work for any Linux distribution that follows the - Filesystem Hierarchy Standard. -- win-x64 -- macos-x64 -- macos-arm64 - -:::caution - -Not all platfoms are supported currently. We have only tested on linux-x64. diff --git a/docs/reference/polykey-cli/commands/secrets.md b/docs/reference/polykey-cli/commands/secrets.md index 5330a665..4f903f7b 100644 --- a/docs/reference/polykey-cli/commands/secrets.md +++ b/docs/reference/polykey-cli/commands/secrets.md @@ -65,7 +65,11 @@ $ polykey secrets dir ~/test-dir vault1 3. If the edited file isn't saved or the editor crashes, the secret will not be written -:::warning This command does not work on Windows yet ::: +:::warning Warning + +This command does not work on Windows yet + +::: Usage: @@ -85,7 +89,11 @@ I edited this secret inside an editor 4. If no paths are specified, this command takes input from `stdin` and prints it to `stdout` -:::tip `^D` in the terminal stands for the key combination 'Ctrl-D' ::: +:::tip Tip + +`^D` in the terminal stands for the key combination 'Ctrl-D' + +::: Usage: @@ -184,7 +192,11 @@ new-name 1. Get the stats of a specified secret from a vault 2. Requires secret location (vaultName:secretName) as a parameter -:::note The mode (or file permissions) doesn't exist within a vault ::: +:::note Note + + The mode (or file permissions) doesn't exist within a vault + +::: Usage: @@ -213,7 +225,10 @@ blocks: 1 2. Run a command with the specified variables, or export them in the current working environment -:::note Separate the environment variables from the command by passing in a `--` +:::note Note + +Separate the environment variables from the command by passing in a `--` + ::: Usage: @@ -253,11 +268,15 @@ do not commit your keys to github 1. Reads input from `stdin` and writes it to the specified file 2. If the file doesn't exist, it gets created -:::tip `stdin`, or standard input, can be either manually entered by typing, or +:::tip Tip + +`stdin`, or standard input, can be either manually entered by typing, or piped in through another command. To close the input steam and save the file, press `^D`, or 'Ctrl-D' in a new -line, or press `^D` twice on the same line. ::: +line, or press `^D` twice on the same line. + +::: Usage: diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md deleted file mode 100644 index 70771834..00000000 --- a/docs/tutorials/README.md +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Tutorials - -The tutorials here are recommended as an introduction to the Polykey ecosystem. - -They allow you to get started using Polykey in a practical manner. - -Each tutorial is categorized under a particular subproject. - - diff --git a/docs/tutorials/polykey-cli/README.md b/docs/tutorials/polykey-cli/README.md deleted file mode 100644 index f2f6489b..00000000 --- a/docs/tutorials/polykey-cli/README.md +++ /dev/null @@ -1,81 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey CLI - -The Polykey Command Line Interface (CLI) is the primary user interface for the -Polykey system, tailored for developers and system administrators. It was -conceived from the necessity of managing secrets efficiently during software -development and deployment workflows. - -## Overview - -The Polykey CLI is the first and primary interface to the Polykey system. It is -intended for developers and system administrators who require an advanced tool -for managing secrets efficiently. New features are introduced in the CLI first, -serving as a testing and integration ground before being ported to other user -interfaces. This approach ensures that the features are reliable and refined for -professional use. - -We designed the CLI user-experience (UX) to be suitable for a human operator, -but also to be easily scripted and integrated into other tools. - -The tutorial here should be followed in order, and the goal is to make use of -Polykey to manage secrets for a simple application from development to -deployment. - -The CLI is open-source and available on GitHub: -[Polykey CLI](https://github.com/MatrixAI/Polykey-CLI). - -### Supported Platforms - -Polykey is continuously built and tested on: - -- Linux x64 / arm64 -- MacOS x64 / arm64 -- Windows x64 -- Docker - -:::note Polykey is currently in beta. Its interface is at various levels of -stability. So bear with us as we perfect its design. You can contribute by -discussing with us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue -tickets in the -[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). ::: - -## Getting Started - -Start your journey with Polykey by following the tutorials below in sequence: - -:::tip For a visual walkthrough, check out our -[getting started demo video](https://vimeo.com/884649667) after installing -Polykey. ::: - -1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install - Polykey CLI on your platform. -2. **[Bootstrap Keypair](/docs/tutorials/polykey-cli/bootstrapping)** - Set up - your node and connect to the network. -3. **[Managing Vaults](/docs/tutorials/polykey-cli/managing-vaults)** - Securely - store secrets within encrypted vaults. -4. **[Managing Secrets](/docs/tutorials/polykey-cli/managing-secrets)** - - Organize and handle secrets within your vaults. -5. **[Claiming Digital Identities](/docs/tutorials/polykey-cli/claiming-digital-identities)** - - Establish and authenticate your identity within the network. -6. **[Discovering Other User's Identities](/docs/tutorials/polykey-cli/discovering-other-users)** - - Find and verify other users to manage permissions. -7. **[Sharing Vaults](/docs/tutorials/polykey-cli/sharing-vaults)** - Share your - encrypted vaults securely with peers. -8. **[Managing Multiple Nodes](/docs/tutorials/polykey-cli/managing-multiple-nodes)** - - Operate multiple local nodes/agents. -9. **[Using Environment Variables](/docs/tutorials/polykey-cli/using-environment-variables)** - - Master `polykey secrets env` for dynamic environment management. - -Explore advanced scenarios in subsequent sections, including: - -- Managing multiple local nodes -- Integrating multiple nodes with a single identity -- Injecting secrets directly into your development environments using Polykey’s - `env` command - -This will prepare you to fully exploit Polykey’s capabilities in diverse and -complex operational settings. - - diff --git a/docs/tutorials/polykey-cli/bootstrapping.md b/docs/tutorials/polykey-cli/bootstrapping.md deleted file mode 100644 index 44aeb7c8..00000000 --- a/docs/tutorials/polykey-cli/bootstrapping.md +++ /dev/null @@ -1,151 +0,0 @@ -# Bootstrapping - -## Introduction - -Bootstrapping is the process where the Polykey agent sets itself up as a new -Polykey node. This involves creating the encrypted-at-rest node state, and -connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified -network domain. - -## Setting Up Your Node - -### Creating the Root Key - -When you first start the Polykey agent, it automatically generates a random root -key. - -This root key is an asymmetric key pair consisting of a public key representing -your identity and used for verifying signatures, and a private key which is used -for signing. - -Afterwards, encryption keys are derived from this root key, which is used for -encryption and decryption of all node state and secret data managed by Polykey. - -You will be prompted to provide a root password. This password encrypts the root -key. - -:::note Remember to keep your password in a secure location as you will need it -each time you start the Polykey agent. ::: - -### Starting the Polykey Agent - -You can start the Polykey agent in the foreground of your terminal by running: - -```bash -polykey agent start --verbose -``` - -Running the agent in the foreground allows you to monitor its output directly in -the terminal. Ensure this terminal session remains active to keep the agent -running. You can execute Polykey commands from any other terminal session while -this runs. - -### Starting Polykey in the Background - -Alternatively, in the demo video and other scenarios where you do not wish to -occupy your terminal, you can start the agent in the background: - -```bash -polykey agent start --verbose --background -``` - -### Stopping the Polykey Agent - -You can stop the Polykey agent by pressing **Control+C** in the terminal where -it's running in the foreground, or by running: - -```bash -polykey agent stop -``` - -#### Troubleshooting - -If the Polykey agent does not terminate properly, you can force quit the process -through the Activity Monitor on your machine. If you encounter this or any other -issue, please consider making a -[bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) to help -improve Polykey. - -## Check Agent Status - -To check the status of your Polykey node, use the following command: - -```bash -polykey agent status -``` - -This command provides detailed information about your node's current state, -including its connectivity and activity within the network. - -### Example Output - -```bash -status LIVE -pid 96992 -nodeId vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg -clientHost ::1 -clientPort 54975 -agentHost :: -agentPort 60358 -upTime 8 -startTime 1716509093 -connectionsActive 3 -nodesTotal 11 -version 1.2.3-alpha.4-1-1 -sourceVersion 1.2.3-alpha.4 -stateVersion 1 -networkVersion 1 -``` - -## Check Network Status - -When your agent has started, it should show as a node on the network. By default -the network is [mainnet](https://mainnet.polykey.com/). Check out the network -dashboard to see your placement on the world map. - -## Monitoring Network Connections - -To view the nodes currently connected to the network, including the seed nodes, -run: - -```bash -polykey nodes connections -``` - -This will list all active connections, including details about each node. - -### Example Output - -```bash -host hostname nodeIdEncoded port timeout usageCount -3.145.86.40 N/A v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0 1314 46873 0 -13.239.117.143 N/A vncm2mkk41vgp2fmplqiu1je7b2l3v6fhgltlqf5f3f85923ve0j0 1314 116186 0 -1.145.55.96 N/A vg6gldhfdstju8frtbguav2p2svmev85dvpdb34gffmiagpgjf2pg 1200 102086 0 -``` - -## Checking Node Activity - -To determine if a specific node is active, use the ping command: - -```bash -polykey nodes ping -``` - -This will tell you whether the node is active within the network. - -### Example Output - -```bash -polykey nodes ping v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0 -Node is Active -``` - -## Conclusion - -Bootstrapping your node is the first step to using Polykey effectively. It -prepares your node for managing and sharing secrets securely within the network. -By following these guidelines, you ensure that your node is well-configured, -secure, and ready for advanced operations in the Polykey ecosystem. - -Stay tuned for upcoming sections where we will discuss managing multiple nodes, -assigning different file paths to each node, and other advanced configurations. diff --git a/docs/tutorials/polykey-cli/claiming-digital-identities.md b/docs/tutorials/polykey-cli/claiming-digital-identities.md deleted file mode 100644 index 3a093a1c..00000000 --- a/docs/tutorials/polykey-cli/claiming-digital-identities.md +++ /dev/null @@ -1,217 +0,0 @@ -# Claiming Digital Identities: Establishing Identity Linkages in Polykey - -In Polykey, claiming a digital identity is a crucial step that allows users to -establish their identity across various platforms and link these identities to -their cryptographic keys. This process involves authenticating with external -services, such as GitHub, and claiming ownership of an identity by posting a -cryptographic link to a publicly verifiable location. - -This tutorial will guide you through the steps to authenticate with GitHub and -claim an identity using Polykey, enhancing security and streamlining identity -verification, making it easier for other users to discover and trust your nodes. - -## Step 1: Authenticate with GitHub - -Authentication with a service provider like GitHub is the first step toward -claiming your digital identity. This process allows Polykey to interact with -GitHub on your behalf and access necessary information to claim your identity. - -![GitHub Authentication](/images/github-authentication.png) - -_This image provides a demo example of the GitHub authentication process._ - -### Command Usage - -:::info - -```bash -polykey identities authenticate -``` - -``: The identifier for the digital identity provider, such as -"github". ::: - -:::note Since Polykey currently only supports GitHub as an IdP, this is the -command that you will use to start the authentication process. - -```bash -polykey identities authenticate github -``` - -::: - -This command begins the authentication process with GitHub. Follow the prompts -in your terminal to complete the authentication, which may involve logging into -your GitHub account and authorizing Polykey to access your GitHub information -via a popup window. - -:::tip The code prompted by the browser will be displayed in your terminal as -the user code. ::: - -### Lists all authenticated identities across all providers - -`polykey identities authenticated` command will output the providerID and -corresponding identityID of the authenticated IdP. This is a way to check that -you completed the authentication process correctly. - -#### Example Usage - -```bash -polykey identities authenticated -``` - -##### Example Output - -```bash -providerId github.com -identityId maverick -``` - -### Technical Use of Permissions - -During the authentication process, here's what Polykey requests access to and -why: - -- **Create Gists:** Polykey creates a gist under your GitHub account containing - a cryptographic link. This link is a verifiable method that proves the - ownership of your GitHub identity to anyone checking your Polykey gestalt - graph. - -- **Read All User Profile Data:** This enables Polykey to access your profile - details, including your username, followers, and public repository data. This - information is used to ensure that the identity you claim corresponds - accurately to your public digital footprint, enhancing trust and verification. - -- **Access User Email Addresses (read-only):** By accessing the email addresses - associated with your account, Polykey can better manage notifications related - to your secrets operations. - -#### Security and Privacy Considerations - -Polykey is committed to maintaining the highest standards of security and -privacy. All data accessed is used strictly for the operations mentioned and is -not shared with any third parties. Our privacy practices are designed to protect -your information and ensure its confidentiality. For more details, please refer -to our [privacy policy](https://polykey.com/privacy-policy). - -## Step 2: Claim Your Identity - -After successfully authenticating with GitHub, you can claim your identity. This -involves posting a cryptographic link to a publicly verifiable location, such as -a GitHub gist. This link serves as proof of ownership of the identity. - -Cryptolink - -### Command Usage - -_This image provides a demo example of the cryptographic link that is -generated._ - -:::info - -- ``: The specific identity identifier from the provider you - authenticated with, which you will claim. - -- `polykey identities claim` argument for `` = `github.com`+ - `:` + `GH username` - -::: - -Replace `my-gh-username` with your actual GitHub username. This command claims -your GitHub identity by posting a cryptographic link to a gist under your GitHub -profile. - -```bash -polykey identities claim github.com:my-gh-username -``` - -## Step 3: Verify Your Claim - -After claiming your identity, Polykey provides a link to a GitHub gist in your -terminal. This is your primary method to verify that your identity has been -correctly claimed. - -![Claim Id](/images/claim-id.png) - -_This image shows a demo example of the link to the gist that was created when -claiming the identity which forms a gestalt._ - -### Primary Verification Method - -Check your GH gists. Replace `my-github-username` with your actual gh username -and navigate to the url. - -```bash -https://gist.github.com/my-github-username -``` - -This gist contains the cryptographic link confirming that your Polykey identity -is correctly linked to your GitHub profile. Viewing this gist ensures your claim -was successful and publicly verifiable. - -## Understanding Gestalt Graphs - -In Polykey, claiming identities creates a **gestalt graph**—a dynamic, -interconnected network of your digital identities across various platforms. This -graph facilitates the federated identity model, allowing for more robust and -streamlined identity verification and management. - -![gestalts](/images/gestalts.png) - -_This image shows a federated gestalt graph example concept map._ - -### How Gestalt Graphs Work - -Each node within the graph represents an identity or a claim, and edges -represent trust relationships or cryptographic verifications. As you claim more -identities or add nodes, the graph expands, enhancing its utility by making -identity verification straightforward and trust relationships more transparent. - -### Claiming Multiple Identities - -Polykey enables you to manage your digital presence flexibly by supporting the -claiming of multiple identities across different scenarios. Specifically, you -can: - -- Link one node to several identity providers (IdPs), broadening your digital - footprint and verification avenues as more IdPs are supported. - -- Claim the same identity provider, such as a GitHub username, across multiple - unique nodes you control, consolidating your digital identity while expanding - your network's reach. - -### Future Plans and IdP Support - -Currently, Polykey supports GitHub as an identity provider (IdP). However, we -are actively working to expand our support to include a wider range of major -IdPs. This expansion will enhance Polykey's accessibility and versatility, -accommodating a broader user base. Additionally, organizations will have the -option to maintain their own IdPs, allowing for even greater customization and -control over identity management within Polykey. - -### Benefits of Federated Identities - -Using a federated identity model through gestalt graphs offers several benefits: - -- **Enhanced Security**: By linking various identity proofs, it strengthens the - authenticity and credibility of your digital identity. -- **Simplified Management**: Manage multiple identities through a single - interface, reducing complexity and improving user experience. -- **Interoperability:** Easily interact across different platforms and services - using a unified identity framework. - -Understanding and utilizing gestalt graphs in Polykey not only secures your -operations but also significantly simplifies the process of digital identity -management. - -## Conclusion - -Claiming your digital identity in Polykey links your cryptographic operations to -external accounts like GitHub, securing your operations and facilitating -identity verification by others. This guide details the essential steps for -authenticating, claiming, and verifying your identity in Polykey. - -In the next section, we will explore additional operations related to digital -identity management in Polykey, including discovery of other users, trust -management and permissions handling. diff --git a/docs/tutorials/polykey-cli/discovering-other-users.md b/docs/tutorials/polykey-cli/discovering-other-users.md deleted file mode 100644 index abccd71d..00000000 --- a/docs/tutorials/polykey-cli/discovering-other-users.md +++ /dev/null @@ -1,220 +0,0 @@ -# Discovering Users' Nodes and Managing Access Permissions - -In the Polykey network, discovering other users' nodes and managing access -permissions is crucial for secure and efficient collaboration. This guide will -walk you through the process of finding other users' nodes using their claimed -digital identities and setting permissions to manage how these nodes interact -with your secrets and vaults. - -## Introduction to Node Discovery and Permission Management - -Discovering nodes in Polykey involves locating other users within the network -who have linked their identities, such as GitHub usernames, to their nodes. Once -these nodes are discovered, you can manage access permissions to control how -these nodes interact with your shared resources. - -This functionality enhances the security of your network by ensuring that only -trusted nodes can access sensitive information. - -## Discovering Nodes - -To begin discovering nodes associated with known identities, you can use the -`polykey identities discover` command. This command adds a node or identity to -your discovery, facilitating further interactions like sharing vaults or -secrets. - -### Command Usage - -```bash -polykey identities discover -``` - -- ``: This can be either a Node ID or a `Provider ID:Identity ID` - combination that specifies the digital identity linked to the node you wish to - discover. - -#### Example - -```bash -polykey identities discover github.com:maverick -``` - -This command adds the node associated with the GitHub username "maverick" to -your discovery queue, allowing you to initiate interactions with this user. -:::note - -## Troubleshooting Discovery and Connection Issues - -When attempting to discover other users' nodes and manage permissions within -Polykey, there are specific requirements and common issues you may encounter. -Understanding and addressing these can ensure smoother operations within the -network. - -### Requirements for Successful Discovery - -1. **Active Polykey Agents:** Both users involved in the discovery must have - their Polykey agents actively running. This ensures that both nodes are - reachable and responsive within the network. - -2. **Network Connection:** Both nodes need to be connected to the Polykey - network. Currently, both users must be online simultaneously for the - discovery process to succeed. - -### Common Issues and Solutions - -1. **Gestalt Creation:** Ensure that the user you are trying to discover has - already created their gestalt. A gestalt is necessary for the identity to be - discoverable in the network. Without it, the discovery process will fail. - -2. **Symmetric NAT or Restrictive Networks:** Connection issues can arise if one - or both users are behind symmetric NATs or other restrictive network setups. - These environments can block the necessary network communications for - successful node discovery. - - - **Solution:** Attempt the discovery process from a network with less - restrictive settings, such as home Wi-Fi or a less secure public network, - to see if the issue persists. - -::: - -:::info - -### Future Enhancements - -Polykey is actively working to enhance the discovery process by implementing -features that would allow one-sided connectivity. This means that in the future, -users may not need to be online simultaneously. One user could initiate a -discovery, akin to sending a friend request, and the other could respond at -their convenience, simplifying the process and reducing the dependency on -simultaneous network presence. - -This section helps users understand the prerequisites for successful node -discovery and provides solutions to common issues that might impede the process. -By following these guidelines, users can more effectively manage their -interactions within the Polykey network. ::: - -## GestaltId and Permissions Explained - -### GestaltId - -The `gestaltId` is a unique identifier that directly links to a node or an -identity within the Polykey network. It can take the following forms: - -- **Node ID:** Directly references a node within the Polykey network. - -- **Provider ID:** Utilizes an identity provider (like GitHub) combined with a - specific user identity (like a username). - -#### Example Format - -- Node ID: `v60g23b4b9g5tq2npc3kpikpalqqdpuvocegdd8bsdj28a1hsp0g0` -- Provider ID: `github.com:maverick` - -### Permissions - -Permissions in Polykey determine what actions a node or an identity can perform -within the network. Here’s a general list of potential permissions that can be -managed: - -- **Read:** Allows viewing but not modifying. -- **Write:** Allows both viewing and modifying. -- **Execute:** Allows performing specific actions. -- **Notify:** Allows sending notifications about changes or updates. -- **Trust:** Allows a node to be trusted, generally affecting how interactions - are secured. - -#### Example Command to Set Permissions - -```bash -polykey identities allow github.com:maverick read write -``` - -## Managing Permissions - -Once a node is discovered, you can manage permissions to control access to your -vaults and secrets. Polykey allows you to set or unset permissions for each -discovered node or identity. - -### Setting Permissions - -To grant specific permissions to a node, use the `polykey identities allow` -command: - -```bash -polykey identities allow -``` - -- `:` The Node ID or `Provider ID:Identity ID` of the node. -- `:` The type of permission you want to allow, such as `read`, - `write`, or `execute`. - -#### Example - -```bash -polykey identities allow github.com:maverick read -``` - -This command grants read permissions to the node associated with the GitHub user -"maverick." - -### Revoking Permissions - -If you need to revoke permissions from a node, you can use the -`polykey identities disallow` command: - -```bash -polykey identities disallow github.com:maverick read -``` - -#### Example - -```bash -polykey identities disallow github.com:maverick read -``` - -This command revokes read permissions from the node associated with "maverick." - -## Additional Management Features - -Polykey also supports inviting nodes to your network, listing all discovered -nodes and their permissions, and setting trust levels for more granular control. - -### Inviting a Node - -To invite another node to join your network and potentially share secrets: - -```bash -polykey identities invite -``` - -### Listing Nodes and Permissions - -To view all nodes and their permissions within your network: - -```bash -polykey identities list -``` - -### Trusting and Untrusting Nodes - -You can explicitly trust or untrust a node to refine how notifications and -access controls are handled: - -```bash -polykey identities trust -polykey identities untrust -``` - -## Conclusion - -Managing node interactions and user discovery in Polykey is vital for -maintaining a secure and efficient network. By carefully managing who can access -your nodes and how they can interact with your resources, you enhance the -overall security and functionality of your network. - -This guide has provided the steps and commands necessary to effectively discover -nodes and manage permissions within Polykey. - -This addition ensures users understand the significance and usage of `gestaltId` -and permissions within the context of discovering and managing nodes in Polykey, -providing clear and actionable information for efficient network management. diff --git a/docs/tutorials/polykey-cli/installation.md b/docs/tutorials/polykey-cli/installation.md deleted file mode 100644 index adf69156..00000000 --- a/docs/tutorials/polykey-cli/installation.md +++ /dev/null @@ -1,468 +0,0 @@ -import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; - -# Installation - -Installing the CLI can be done in different ways depending on your operating -environment. - -:::info - -Polykey-CLI has only been tested on Linux and macOS. We are working on -supporting other platforms. There's minor teething problems when it comes -supporting other platforms. Help us by reporting any issues with the CLI tool in -our Github Repo -[here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping -a message to the developers in our discord server -[here](https://discord.gg/dC32r35TeE). - -::: - - - - -## Linux - -Polykey-CLI code is compiled, bundled and wrapped into a single file executable. -You just have to download the executable, give it executable permissions and run -it. The executable is not statically linked. It requires a subset of the system -libraries that Node.js requires. - -- `libdl.so.2` -- `libstdc++.so.6` -- `libm.so.6` -- `libgcc_s.so.1` -- `libpthread.so.0` -- `libc.so.6` - -### Manually - -Builds for Linux is released on GitHub: -https://github.com/MatrixAI/Polykey-CLI/releases. - -Download the executable named `...-polykey-cli-V.V.V-linux-x64`, and rename it -to `polykey`. - -Make it executable: - -```sh -$ chmod u+x ./polykey -``` - -### Add it to your `$PATH`. - -#### For ZSH: - -1. `cd` into directory where polykey exec is stored. -2. Edit the zsh config to add polykey to your path. To streamline the process, - run the following command, making sure to change the path to polykey if the - polykey executable is not in the downloads folder. -3. For most users, this would be `~/Downloads` - -:::warning - -Make sure your path to the polykey executable is correct. - -::: - -```sh -$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc -``` - -You only need to run this command once. After running this command, you can now -invoke polykey by typing `polykey` into the terminal. - ---- - -#### For Bash: - -1. `cd` into directory where polykey exec is stored. -2. Edit the zsh config to add polykey to your path. To streamline the process, - run the following command, making sure to change the path to polykey if the - polykey executable is not in the downloads folder. -3. For most users, this would be `~/Downloads` - -:::warning - -Make sure your path to the polykey executable is correct. - -::: - -```sh -$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc -``` - -You only need to run this command once. After running this command, you can now -invoke polykey by typing `polykey` into the terminal. - ---- - -### NixOS - -We have not yet published a Nix package for Polykey. When we do, you will be -able to just install `polykey-cli` from Nixpkgs. - -However, it is easy enough to install it from source. - -Clone the repository: - -```sh -$ git clone https://github.com/MatrixAI/Polykey-CLI.git -``` - -Enter the `nix-shell`: - -```sh -$ nix-shell -``` - -Build the application and install it into the user profile: - -```sh -$ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)" -``` - -### Other - -We will be working on other distribution methods. - - - - -## MacOS - -:::info - -ARM-64 builds are not currently supported on MacOS as of **26-03-24.** However, -building Polykey yourself on MacOS resolves in a working binary. Follow this -guide below to manually build and install Polykey on macOS. - -::: - -### Manually - -1. Download the Polykey CLI for macOS from the - [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases). - Look for the file named `polykey-cli-V.V.V-darwin-universal`, where `V.V.V` - is the version number. For Mac, you want to download the file with the - `darwin-universal` file extension. - -2. Rename the downloaded file to `polykey` for easier access. In your terminal, - make sure to navigate to the directory where the file is located (usually the - Downloads directory) and run the following command: - -```sh - mv polykey-cli-V.V.V-darwin-universal polykey -``` - -:::tip - -- Navigate into the directory where the file is saved to execute commands. -- Replace `V.V.V.` with the actual version number of the file you downloaded. - -::: - -3. Make the Executable Runnable: Before you can run the Polykey CLI, you need to - make it executable. Use the `chmod +x` command to add executable permissions - to the file. Replace `polykey` with the actual name of your file if it's - different: - -```sh -chmod +x polykey -``` - ---- - -### MacOS Security Bypass - -MacOS requires additional steps for the binary to be allowed to execute, this is -due to the fact that as of 20-12-23, the binaries we release are unsigned, and -MacOS permits running of unsigned binaries, however, to progress past this, -there are a couple options: - - - - - #### Method #1 - quickest method - -The `xattr` command will remove the quarantine attribute from the Polykey -executable, allowing you to run it without triggering macOS security warnings. -Remember to ensure that the file path matches the location of your polykey file. - -```sh -sudo xattr -r -d com.apple.quarantine ~/Downloads/polykey -``` - -If you have completed this sucesfully, you may ignore Method #2 and move to the -next section on how to add polykey to your `$PATH`. - -## - ---- - - - - -#### Method #2 - Using the Apple Systems Settings GUI - -First type the following command to try running the Polykey CLI but will instead -trigger a pop-up. - -```sh -./polykey --version -``` - -1. MacOS will then prompt you with the following: - -:::important Do not close this prompt. If you do, the 'Allow Anyway' option will -not appear in the next step. ::: - -![install1](/images/mac-install1.png) - -2. While keeping the prompt open, head over to `Settings -> Privacy & Security` - and scroll down till you see '"polykey" was blocked from use because it is - not from an identified developer.' - -![install2](/images/mac-install2.png) - -3. Click on `Allow Anyway` and authenticate. - -4. Try opening polykey with - -```shell -sudo ./polykey -``` - -:::tip When prompted in the terminal, type your administrator password and hit -enter. ::: - -5. Following this, you will get another similar prompt - -![install3](/images/mac-install3.png) - -#### Click on Open and now Polykey-CLI should be running in your terminal window. - -:::tip You can also verify the version of polykey that was installed with: - -```sh -./polykey --version -``` - -::: - ---- - - - - -### Add Polykey to your `$PATH`. - -To enable running the Polykey CLI from any directory in the terminal on macOS, -you'll need to update your shell configuration file. - - - - -#### For ZSH (default shell on recent macOS versions): - -1. Navigate (cd) into the directory where the "polykey" executable is stored. - -2. Edit the Zsh configuration file to add "polykey" to your $PATH. Use the - following command, ensuring to replace ~/Downloads with the correct path to - the "polykey" executable if it's not in the downloads folder. For most users, - this path would be ~/Downloads on Debian-based systems. - -:::tip - -Make sure your path to the "polykey" executable is correct. - -::: - -```sh -echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc -``` - - - - -#### For Bash: - -1. `cd` into the directory where the "polykey" executable is stored. -2. Edit the Bash config to add "polykey" to your path. To streamline the - process, run the following command, making sure to change the path to - "polykey" if the executable is not in the downloads folder. For most users, - this would be `~/downloads` on Debian-based systems. - -:::tip - -Make sure your path to the "polykey" executable is correct. Replace `downloads` -with the path to the working directory - -::: - -```sh -echo 'export PATH=~/downloads:$PATH' >> ~/.bashrc && source ~/.bashrc -``` - - - - -:::tip - -You can check if the PATH environment variable for Polykey has been updated -correctly by running: - -```sh -polykey --version -``` - -If this command returns the current version, then you have successfully added -Polykey to your PATH, and you can now run polykey from anywhere in your -terminal. - -::: - - - - -:::warning - -Polykey for windows should be working but we have yet to create documentation on -the installation process for this. - -::: - - - - -## Docker - -The Docker image can be used so that Polykey can be deployed into the cloud. It -is also possible to use the CLI via the docker container, but it isn't as -convenient. The intention is to run the Polykey agent in the cloud. - -Docker images is released on GitHub: -https://github.com/MatrixAI/Polykey-CLI/releases. - -Download the image named `...-docker-image-polykey-cli-V.V.V.tar.gz` and rename -it to `docker-image-polykey-cli.tar.gz`. - -Load it into Docker: - -```sh -loaded="$(docker load --input "$(nix-build ./release.nix --attr docker --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)")")" -image="$(cut -d' ' -f3 <<< "$loaded")" -docker run -it "$image" -``` - -### Docker for Mac - -:::tip - -You can install nix for MacOS and then follow the general docker instructions -above. Nix for mac can be installed by running - -```sh -sh <(curl -L https://nixos.org/nix/install) -``` - -::: - -1. Download the latest build of Polykey-CLI for docker from - https://polykey.com/download. - -2. Download Docker for MacOS depending on your instruction-set (arm vs x86) from - https://docs.docker.com/desktop/install/mac-install/ - -3. Rename the Polykey dist from - `x-docker-image-polykey-cli-x.x.x-alpha.x.tar.gz` to `docker-polykey.tar.gz` - -4. Load the image in docker using the following: - -```shell -docker load --input docker-polykey.tar.gz -``` - -5. Go to your docker application and configure the Polykey image - -![img.png](/images/docker-mac-img1.png) - -6. Run `mkdir /tmp/polykey` to create a directory for the polykey nodepath - -7. Set the volume host path to `/tmp/polykey` and the container path to - `/tmp/polykey/` - -8. Run `docker images` to grab the Image ID of your installed image. - -```shell -> docker images -REPOSITORY TAG IMAGE ID CREATED SIZE -polykey-cli-0.1.2-alpha.2 gygbx1qgpnhbvbcbaby3sfm19bamg7sx 0e1addd9855a 12 days ago 370MB -``` - -9. Now you can run Polykey as an agent with the following shell command - -```shell -docker run -it 0e1addd9855a agent start --background -np /tmp/polykey -``` - -Making sure to replace `0e1addd9855a` with your corresponding image ID. - -```shell - docker run -it 0e1addd9855a agent start --background -np /tmp/polykey -WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested -✔ Enter new password … * -✔ Confirm new password … * -pid 28 -nodeId vflhiouqt255gq22drpf0s639kl9eds3ralu094c6rsnmonemp6pg -clientHost 127.0.0.1 -clientPort 45509 -agentHost :: -agentPort 37468 -recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly whip simple warfare daughter pepper detail bachelor awkward forget ignore cream silly raw - -``` - - - - -## Node Package Manager - -The CLI is published as -[`npm` package](https://www.npmjs.com/package/polykey-cli). - -Install it with: - -```sh -npm install -g polykey-cli -``` - -This will install the Polykey-CLI into the path pointed to by the command -`$(npm config get prefix)`. - -If the `npm` bin path is added to the `$PATH` environment variable, then you -will be able to execute `pk` or `polykey`. - - - - -## Source - -The official source repository is on GitHub. There is an additional mirror on -GitLab. - -```shell -git clone https://github.com/MatrixAI/Polykey-CLI.git -``` - -Use `npm install` to setup the project. - -:::tip - -If you have `nix-shell` available, enter into `nix-shell` and it will -automatically setup the development environment. - -::: - - - - diff --git a/docs/tutorials/polykey-cli/managing-multiple-nodes.md b/docs/tutorials/polykey-cli/managing-multiple-nodes.md deleted file mode 100644 index 4adc59fb..00000000 --- a/docs/tutorials/polykey-cli/managing-multiple-nodes.md +++ /dev/null @@ -1,164 +0,0 @@ -# Managing Multiple Local Nodes - -Managing multiple local - -nodes in Polykey can serve various purposes. For example, you might maintain one -node for personal projects and another for professional work. This segregation -ensures that the vaults and their respective contents remain distinct based on -their usage context. - -This approach is particularly advantageous for demonstrations or training -purposes, as it allows you to simulate sharing vaults between two nodes on the -network without requiring another live user. It also enables a robust -environment for testing node interactions and features in a controlled manner. - -Each node in Polykey operates with its own dedicated agent, and nodes are stored -locally with specified node paths. When you first initialize Polykey, a default -node and its path are created. This default node path can be viewed by running -specific Polykey commands, which we will cover. To manage multiple nodes -effectively, each node you create will have its designated node path that -directs all operations specifically to that node's environment. - -## Understanding Node Paths - -The default node, which you bootstrap when you first install Polykey, resides at -a standard location on your file system. This location can be found using: - -```bash -polykey nodes --help -``` - -For any additional nodes, such as nodeB, you will specify a new node path during -their creation. This is critical because each node operates independently, -requiring its unique path for all interactions: - -```bash -polykey agent start --node-path ./nodeB --background -``` - -This command initializes a Polykey agent using the nodePath flag to specify the -node we are starting an agent for. If unsure of the syntax to use for command -operations, adding the --help at the end of each subcommand provides useful -context. - -:::note If a node has not been created before, initializing the Polykey agent -for it will also initiate the bootstrap process. ::: - -When working with multiple nodes, specifying the node path in each command can -become cumbersome. To streamline this process in your terminal shell session, -you can set an environment variable for the node path, which we will demonstrate -later. - -## Steps to Manage Multiple Nodes Locally - -### 1. Initialize Your Nodes - -Open two terminal sessions (Shell A for your default node and Shell B for your -new node that we will save a new path called nodeB). If you have not already -started the Polykey agent for your default node, you can start it as follows: - -**Shell A (default node):** - -```bash -polykey agent start --background -``` - -This initializes your default node in the background. The command does not -specify a node path, so it automatically targets the default node path. - -**Shell B (for your new node, nodeB):** - -```bash -polykey agent super_start --node-path ./nodeB --background -``` - -This command starts a new Polykey agent for nodeB in the background. The first -time you run this, it will prompt you to set a password, just like bootstrapping -any new node. Remember, each node operates with its dedicated agent, ensuring -that their operations are isolated from each other. - -### 2. Configure Node Environment - -To avoid having to specify the node path for every command in a session: - -#### **Export the environment variable in Shell B:** - -```bash -export PK_NODE_PATH='./nodeB' -``` - -This sets the environment for nodeB in Shell B, allowing you to execute Polykey -commands specific to nodeB without constantly adding the node-path flag. - -### 3. Verify Node Status - -In both shell sessions, check that each node is active: - -```bash -polykey agent status -``` - -This command confirms the node's status and provides the nodeId, which is -crucial for the next steps. - -### 4. Node Discovery and Trust Establishment - -Before sharing any vaults, both nodes need to discover each other and establish -trust. Use the `nodeId` obtained from the status output: - -#### **Shell A (default node):** - -```bash -polykey identities discover -polykey identities trust -``` - -#### **Shell B (nodeB):** - -```bash -polykey identities discover -polykey identities trust -``` - -### 5. Share a Vault from the Default Node to nodeB - -Choose a vault to share, for example, `Weather-Ops`. - -#### **Shell A (default node):** - -```bash -polykey vaults share Weather-Ops -``` - -### 6. Access the Shared Vault from nodeB - -#### **Shell B (nodeB):** - -```bash -polykey vaults scan -polykey vaults clone Weather-Ops -``` - -These commands list and then clone the shared vault to nodeB's local storage. - -### 7. Validate the Operation - -Check that the vault is now available in nodeB: - -#### **Shell B (nodeB):** - -```bash -polykey vaults list -``` - -## Conclusion - -This tutorial demonstrated how to set up and manage multiple local nodes using -Polykey. You learned to initialize nodes, configure sessions, discover and trust -other nodes, share vaults, and access shared resources. Such a setup is -invaluable for developers managing separate environments for different projects -or testing functionality without another user. - -This approach not only streamlines the management of multiple nodes but also -ensures that all operations are performed securely and efficiently within -controlled environments. diff --git a/docs/tutorials/polykey-cli/managing-secrets.md b/docs/tutorials/polykey-cli/managing-secrets.md deleted file mode 100644 index be040353..00000000 --- a/docs/tutorials/polykey-cli/managing-secrets.md +++ /dev/null @@ -1,389 +0,0 @@ -# Managing Secrets - -## Introduction - -Secrets in Polykey are essential for securely managing sensitive information, -such as API keys, configuration files, or documents. These can be any file type -that you need to encrypt and manage securely. This section provides a detailed -guide on how to manage these secrets within vaults using Polykey-CLI. - -:::tip - -In the Polykey CLI, you can get help with managing your Secrets Operations by -using the `-h` help command to get a detailed list of availiable options and -commands. Try running `polykey secrets -h` ::: - -## Creating Secrets - -:::note - -**Create a Secret within a given Vault** - -**Usage:** `polykey secrets create [options] ` - -**Arguments:** - -**directoryPath:** On disk path to the secret file with the contents of the new -secret. - -**secretPath:** Path to the secret to be created, - -specified as `:` ::: - -### Adding a Secret to a Vault - -The `polykey secrets create` command clones an existing file from your local -machine and stores it into an encrypted vault, creating a secret in the process. -Thus, providing secure data-at-rest encryption of the file. - -:::tip To create a secret, both the vault and file you are creating a secret -from, must already exist. Remember that to view the vaults contained within a -node, you run `$polykey vaults list`. This is useful for viewing the names of -the vaults you are trying to manage secrets with, as vaultName is one of the -command arguments that is commonly used. ::: - -#### Command Arguments - -```bash -polykey secrets create : -``` - - - -:::info The `` for the file you are trying to create a secret from can -either be a working directory filepath or a root path. Also notice that we -either have 1 space of seperation or a `:` between command arguments usually. -The angle braces are just being used in our explanation for specifying the -arguments more clearly. ::: - -#### Example Usage of `Polykey Secrets Create` - -```bash -polykey secrets create ./API_ACCESS_KEY.txt my-api-vault:API_ACCESS_KEY -``` - -This command cloned the `API_ACCESS_KEY.txt` file from the terminal's working -directory and saved it in a vault named `my-api-vault`, specifying the -secretName alias as `API_ACCESS_KEY`. We could have also provided the secretName -alias as `API.ACCESS_KEY.txt` but for most text files in Polykey, specifying the -file type extension is redundant. - -:::tip Since the secret or `` stored in the vault does not specify -the file type in its metadata, when you are storing binary files such as images -or videos, you may want to specify the file extension in the `secretName` alias -for better access & manageability. ::: - -## Listing Secrets - -:::note **List all Available Secrets for a Vault** - -**Usage:** `polykey secrets list|ls [options] ` - -**Arguments:** - -**vaultName:** Name of the vault to list secrets from - -::: - -To list the secret file(s) stored within a specific vault in your default -nodePath, use: - -#### Command Arguments: - -```bash -polykey secrets list -``` - -#### Example Usage - -```bash -Polykey secrets list my-api-vault -``` - -#### Example Output - -In this case, there's just one secret file contained in this vault, the secret -we created in the previous example. - -```bash -API_ACCESS_KEY -``` - -:::note - -### Secure Deletion of Local Secrets - -After adding a secret to a vault, securely delete the local copy if it's no -longer needed. This ensures that no unsecured traces of sensitive information -remain on your local filesystem. ::: - -## Retreiving Secrets - -Retrieve a secret from the given vault using the polykey secrets get command. -This command accesses the encrypted content within a vault and outputs it, -allowing for further handling depending on the file type. - -:::note - -Retrieve a Secret from the Given Vault - -**Usage:** `polykey secrets get [options] ` - -**Arguments:** - -**secretPath:** Path to where the secret to be retrieved, - -specified as `:` - -::: - -### Text and Binary File Handling - -The nature of the file affects how it is handled when retrieved: - -- **Text Files:** Files such as .txt, .cfg, or script files like .sh are - inherently text-based and can be displayed directly in the terminal. This - feature is useful for quick checks and edits directly from the command line. - -- **Binary Files:** Files like images, executables, or other non-text formats - are binary files. These do not display readable content directly in the - terminal and must be handled differently. - -### Retrieving a Text File - -To view the contents of a text file stored in a vault directly from the -terminal, use the following command: - -```bash -polykey secrets get : -``` - -#### Example: Retrieving a Text File - -Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault-tutorial-1` - -```bash -polykey secrets get my-vault-tutorial-1:API_ACCESS_KEY -``` - -#### Example Output - -```bash -AKfjd39jdi3903KDje93j04j0 -``` - -This method displays text files directly in the terminal, providing immediate -access to the contents. - -### Retrieving Binary File - -Binary files, such as images or executables, need to be handled appropriately to -view or use their contents correctly. - -#### Steps to Retrieve a Binary File - -To retrieve and handle a binary file, specify the output format by redirecting -the output to a file with the appropriate file extension: - -```bash -polykey secrets get : > . - -``` - -This command saves the binary content into a file in the current local -directory, preserving the file type as indicated by the extension ``. - -#### Example: Retrieving and Viewing an Image - -Retrieve an image stored in a vault and view it using system-specific commands: - -```bash -polykey secrets get my-NFT:Dali.png > Dali.png -open Dali.png -``` - -:::note The use of `>` in the command line is a standard Unix redirection -operator, used here to direct the output from Polykey into a file. This -operation is necessary for handling binary files that require specific -applications to open. ::: - -:::tip Ensure the secret name includes the file extension (like Dali.png), which -helps clarify the file type when saving and accessing the retrieved file. ::: - -## Creating a Directory of Secrets - -To create a directory within a vault, use the polykey secrets mkdir command. -This command allows you to organize your secrets into directories within a -vault. - -```bash -polykey secrets mkdir : -``` - -#### Example: Creating a Directory in a Vault - -To create a directory named "NFTs" within the "my-image-vault": - -```bash -polykey secrets mkdir my-image-vault:NFTs -``` - -### Adding a Secret to a Directory in a Vault - -After creating a directory, you can add secrets to it. This helps in organizing -similar types of secrets under a common directory. - -```bash -polykey secrets create :/ -``` - -#### Example: Adding a Secret to a Directory - -To add the file "Dali.png" as a secret named "Dali.png" to the "NFTs" directory -within "my-image-vault": - -```bash -polykey secrets create ./Dali.png my-image-vault:NFTs/Dali.png -``` - -:::note To view secrets saved within a directory in a vault, using the -`polykey secrets list ` command for that vault will output all -secrets in the vault, including those within directories. - -**Example Usage** - -```bash - polykey secrets list my-image-vault -``` - -**Output** - -```bash -NFTs/Owner.png -``` - -::: - -## Renaming a Secret - -To rename an existing secret: - -```bash -polykey secrets rename : -``` - -:::tip Use the `secrets list` command to check on your renamed secretFile. ::: - -## Updating a Secret - -To update the contents of an existing secret: - -```bash -polykey secrets update : -``` - -#### Example: Secrets Update - -```bash -polykey secrets update ./rare-dali.png my-image-vault:NFTs/Dali.png -``` - -:::info This is essentially replacing the file content of an existing secret -while preserving the identity of the secret. One way to verify that the update -was performed sucesfully is by viewing the mtime (modified time) timestamp from -the `secrets stat` command. ::: - -## Retrieving Secret Metadata - -To view metadata about a secret: - -```bash -polykey secrets stat : -``` - -#### Example: Viewing Metadata for a Secret - -```bash -polykey secrets stat my-image-vault:NFTs/Dali.png -``` - -#### Example Output - -```yaml -dev 0 ino 158 mode 33188 nlink 1 uid 0 gid 0 -rdev 0 size 23450 atime Sat May 25 2024 17:22:34 GMT-0600 -mtime Sat May 25 2024 17:22:33 GMT-0600 ctime Sat May 25 2024 17:22:33 -GMT-0600 birthtime Fri May 24 2024 22:42:43 GMT-0600 blksize 4096 blocks 6 -``` - -:::note - -### Understanding Metadata Terms - -- **dev:** Device number on which the file resides. -- **ino:** File's inode number. -- **mode:** File permission and type encoded in numeric format. -- **nlink:** Number of hard links. -- **uid:** User ID of file's owner. -- **gid:** Group ID of file's owner. -- **rdev:** Device ID (if special file). -- **size:** File size in bytes. -- **atime:** Last access timestamp. -- **mtime:** Last modification timestamp. -- **ctime:** Last status change timestamp. -- **birthtime:** Creation time of the file. -- **blksize:** Block size for filesystem I/O. -- **blocks:** Number of 512-byte blocks allocated. - -::: - -## Deleting Secrets - -To remove a secret from a vault: - -```bash -polykey secrets delete : -``` - -#### Example: Deleting a Secret - -```bash -polykey secrets list my-image-vault -``` - -**Output:** - -```bash -NFTs/Dali.png -THE_THIEF.png -``` - -```bash -polykey secrets delete my-image-vault:THE_THIEF.png -``` - -Successful deletion does not produce output. Verify the secret was removed by -listing secrets in the vault. - -```bash -polykey secrets list my-image vault -``` - -**Output:** - -Notice that we have sucesfully removed one of the secrets from the vault now. - -```bash -NFTs/Dali.png -``` - -## Editing Secrets in a Vault - -To edit a secret directly within a Vault using Polykey: - -```bash -polykey secrets edit : -``` - -:::warning Polykey Secrets Edit on Mac OS has a bug that we are investigating. -Use Polykey Secrets Update in the meantime. ::: diff --git a/docs/tutorials/polykey-cli/managing-vaults.md b/docs/tutorials/polykey-cli/managing-vaults.md deleted file mode 100644 index f380be56..00000000 --- a/docs/tutorials/polykey-cli/managing-vaults.md +++ /dev/null @@ -1,136 +0,0 @@ -# Managing Vaults - -## Introduction - -Vaults in Polykey are secure containers where you can store and manage secrets -like passwords, tokens, certificates, and keys. Vaults are encrypted and only -accessible within your Polykey node. This section covers the basics of managing -vaults, including creating, listing, deleting, viewing vault history, and -renaming them. - -## Creating a Vault - -To create a new vault, use the following command: - -```bash -polykey vaults create -``` - -#### Example - -Create a new vault named `myvault`: - -```bash -polykey vaults create myvault -``` - -#### Example Output - -```bash -Vault zUvPxC9aKNw94E1yR9dffzY created successfully -``` - -## Listing Vaults - -To see all the vaults you have, use the list command. This provides a simple way -to view all vault names and their identifiers. - -```bash -polykey vaults list -``` - -#### Example Output - -```bash -my-software-project zD8XRJw2SoRoUW5e2mBR9tJ -myvault zD3cWJLBDEMWcbwNbjuUevo -myvault-101 zErezdpLocYs1VRZPV3wcqS -``` - -## Deleting a Vault - -If you need to remove a vault, you can delete it using the delete command: - -```bash -polykey vaults delete -``` - -#### Example - -Delete the vault named myvault: - -```bash -polykey vaults delete myvault -``` - -This operation does not produce output on successful execution, indicating the -vault has been removed. - -## Viewing Vault History - -Each vault maintains a version history which tracks changes over time. Use the -log command to view the history of commits to a vault. - -```bash -polykey vaults log -``` - -#### Example - -View the log for `my-software-project`: - -```bash -polykey vaults log my-software-project -``` - -#### Example Output - -```bash -commitId b568873376cd74a6c58755f73d1068cbb52cbc84 -committer vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg -timestamp Tue May 14 2024 21:27:52 GMT-0600 (Mountain Daylight Time) -message "AWS_SECRET_ACCESS_KEY added\n" -commitId 4d664db1f90f4c03d6c72be0fba4d3d1a3e7bda0 -committer vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg -timestamp Tue May 14 2024 21:27:43 GMT-0600 (Mountain Daylight Time) -message "AWS_ACCESS_KEY_ID added\n" -``` - -## Renaming a Vault - -To change the name of an existing vault, use the rename command. This allows you -to update the vault's name to something more descriptive or appropriate. - -```bash -polykey vaults rename -``` - -#### Example - -Rename `myvault-1` to `myvault-101`: - -```bash -polykey vaults rename myvault-1 myvault-101 -``` - -Confirm the rename by running: - -```bash -polykey vaults list -``` - -## Conclusion - -Managing vaults is a foundational skill in using Polykey effectively. This -section has guided you through the essential commands needed to create, manage, -and organize your vaults within Polykey. Further capabilities such as setting -permissions, sharing vaults, and pulling vaults from other nodes will be covered -in the Secrets Management section of our documentation. These basic -functionalities ensure that your secrets are well-organized and secure within -the network. - -For a full list of vault commands and options, run: - -```bash -polykey vaults -h -``` diff --git a/docs/tutorials/polykey-cli/sharing-vaults.md b/docs/tutorials/polykey-cli/sharing-vaults.md deleted file mode 100644 index 335a27bd..00000000 --- a/docs/tutorials/polykey-cli/sharing-vaults.md +++ /dev/null @@ -1,130 +0,0 @@ -# Sharing Vaults With Secrets - -In Polykey, sharing vaults containing secrets is essential for collaborative -environments. This guide will walk you through the process of securely sharing -your vaults and enabling other users to access and synchronize secrets between -trusted nodes. - -## Prerequisites for Sharing Vaults - -Before sharing a vault, ensure that both nodes have established trust and -appropriate permissions are set. For details on setting trust and access -permissions, refer to the "Discovering Users' Nodes and Managing Access -Permissions" section. - -### Common Debugging Techniques for Sharing Secrets - -To share secrets between two nodes on different machines, both must be actively -connected to the Polykey network. Here are some techniques to ensure -connectivity and troubleshoot common issues: - -- **Node Ping:** Use `polykey nodes ping ` to check if the intended - recipient's node is active and reachable. - -- **Restarting Polykey Agent:** If connectivity issues persist, try restarting - the Polykey agent. Persistent errors might indicate restrictive network - settings blocking communication. - -- **Network Alternatives:** Connectivity issues may also be due to restrictive - networks, try connecting from a different network environment. - -- **Multiple Nodes:** To test sharing functionality without another user, set up - multiple nodes on your system. Refer to the managing multiple nodes section - for guidance. - -## Sharing the Vault - -Share a vault with another node using the `polykey vaults share` command: - -```bash -polykey vaults share -``` - -- ``: The name of the vault you wish to share. -- ``: The Node ID of the node you are sharing the vault with. - -:::tip - -Remember, you can run the following commands to reference the argument names to -pass into your command: - -- `polykey vaults list` -- `polykey identities list` - -::: - -### Example - -```bash -polykey vaults share my-software-project v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 -``` - -This command shares the "my-software-project" vault with the specified node. - -## Receiving a Shared Vault - -### Scanning for Available Vaults - -Once a vault is shared, the recipient should scan for available vaults: - -```bash -polykey vaults scan -``` - -- ``: The Node ID of the node that shared the vault with you. - -#### Example - -```bash -polykey vaults scan v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 -``` - -This command lists the vaults shared by the specified node. - -## Cloning the Shared Vault - -After identifying the shared vaults, the recipient can clone the desired vault -to their own local node: - -```bash -polykey vaults clone -``` - -- ``: The name of the vault to be cloned. -- ``: The Node ID from which to clone the vault. - -### Example - -```bash -polykey vaults clone myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 -``` - -This command clones "myvault" from the specified node to the local system. - -## Synchronizing Changes - -If updates are made to the original vault, such as key rotations or new secrets -added, the receiving node can synchronize these changes by pulling the latest -version of the vault: - -```bash -polykey vaults pull -``` - -- ``: The name or ID of the vault to update. -- ``: (Optional) The node ID from which to pull updates. - -### Example - -```bash -polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 -``` - -This command updates "myvault" with the latest changes from the specified node. - -## Conclussion - -Sharing and synchronizing vaults in Polykey enhances collaboration and security -across the network. By following these guidelines, users can effectively manage -sensitive data, ensuring all parties involved have secure and up-to-date access -to shared resources. diff --git a/docs/tutorials/polykey-cli/using-environment-variables.md b/docs/tutorials/polykey-cli/using-environment-variables.md deleted file mode 100644 index 536bc7d1..00000000 --- a/docs/tutorials/polykey-cli/using-environment-variables.md +++ /dev/null @@ -1,171 +0,0 @@ -# Using Environment Variables with Polykey - -Polykey revolutionizes the management of environment variables by injecting them -securely into applications, surpassing traditional `.env` file methods. This -tutorial delves into the capabilities of the `polykey secrets env` command, -illustrating its versatility and offering detailed usage examples. - -## Introduction - -Environment variables are essential for configuring applications outside the -codebase, managing sensitive data such as API keys and database connections. -Traditional `.env` file approaches expose these to risks such as accidental -exposure and plaintext storage vulnerabilities. Polykey addresses these issues -by storing environment variables in encrypted vaults and injecting them -dynamically into applications, enhancing security and usability. - -### Key Features of `polykey secrets env` - -- **Encrypted Storage:** Secrets are safely stored within encrypted vaults. -- **Dynamic Injection:** Direct injection of secrets into applications minimizes - exposure. -- **Decentralized Secure Sharing:** Supports encrypted secret sharing across - collaborative environments. -- **Cross-Platform Compatibility:** Adapts to different operating systems with - various output formats. - -## Prerequisites - -Before proceeding, ensure Polykey is installed on your system. Familiarize -yourself with creating vaults and managing secrets within Polykey. - -## Tutorial Structure - -This tutorial is structured to cover a range of scenarios illustrating the use -of the `polykey secrets env` command, ensuring you understand how to apply it -effectively across different contexts. - -## Use Cases and Examples - -### 1. Running Applications with Secure Environment Variables - -Inject secrets directly into your applications at runtime, the most common and -critical use case for the polykey secrets env command. - -#### Example: Start an application with a secure API key - -```bash -polykey secrets env --env Weather-Ops:API_KEY -- node app.js -``` - -This will execute `app.js` with the `API_KEY` set, sourced from the -`Weather-Ops` vault. - -### 2. Outputting Environment Variables - -When you need to verify or debug environment variables without executing an -application, you can output them in different formats. - -#### Unix-like Systems Example - -```bash -polykey secrets env --env-format unix --env Weather-Ops:API_KEY -``` - -#### JSON Format Example - -```bash -polykey secrets env --env-format json --env Weather-Ops:API_KEY -``` - -These commands display the environment variables in the console, useful for -validation. - -### 3. Managing Variable Name Conflicts - -Handle potential conflicts with invalid or duplicate environment variable names -efficiently. - -#### Ignore Invalid Names Example - -```bash -polykey secrets env --env-invalid ignore --env Weather-Ops:API_KEY -- node app.js -``` - -#### Overwrite Duplicates Example - -```bash -polykey secrets env --env-duplicate overwrite --env Weather-Ops:API_KEY -- node app.js -``` - -These settings help manage potential variable name issues dynamically during -runtime. - -### 4. Cloud Services Integration - -Showcase integrating with cloud services like AWS using securely managed -secrets. - -#### AWS CLI Integration Example - -```bash -polykey secrets env --env AWS-Creds:AWS_ACCESS_KEY_ID,AWS-Creds:AWS_SECRET_ACCESS_KEY -- aws s3 ls -``` - -This securely passes AWS credentials to the AWS CLI. - -## Managing Secrets Across Environments - -Discuss how to handle secrets in various environments such as development, -staging, and production, using different vaults or nodes. - -### Dynamic Environment Handling Example - -```bash -export PK_NODE_PATH='./prodNode' -polykey secrets env --env Production-Vault:SECRET_KEY -- node deploy.js -``` - -This facilitates secure management of different operational environments. - -## Conclusion - -The `polykey secrets env` command significantly enhances the security and -management of environment variables. It allows for the dynamic and secure -handling of sensitive data across different stages of development and -deployment. - -## Additional References - -We encourage you to delve deeper into Polykey and consider integrating it into -your workflows. For further insights and to participate in community -discussions, please explore the following resources: - -- [Demo on replacing dotenv libraries with `polykey secrets env`:](https://polykey.com/blog/introducing-polykey-a-future-security-standard-for-replacing-dotenv-libraries) - Discover how Polykey can replace traditional dotenv libraries to enhance your - project's security. -- [Using Polykey for secure access to cloud providers:](https://polykey.com/blog/introducing-a-new-standard-in-environment-secrets-management-with-polykey) - Learn how Polykey facilitates secure interactions with cloud services. - -## Tying It All Together - -**1. Initial Setup by User A:** - -- User A sets up a project repository utilizing environment variables stored in - a Polykey vault. - -**2. Collaboration with User B:** - -- User B, collaborating on the same project, requires access to the same - environment variables to maintain consistency and functionality. - -**3. Secure Sharing:** - -- User A shares the vault with User B securely through Polykey. Once User B - clones the vault, they can immediately use the custom script to inject the - necessary environment variables into their session, replicating User A’s setup - effortlessly. - -**4. Customization of Environment Variables:** - -- While some environment variables are shared, certain project-specific - variables may need to be adjusted. Both users can modify their respective - vaults or scripts as needed to accommodate these unique requirements. - -## Experiment with Polykey - -To see this process in action, consider following our detailed guide in the -dotenv library replacement demo. This demo provides hands-on experience with -simulating the secure environment variable sharing between two nodes controlled -by you, illustrating the practical benefits and ease of using Polykey in -collaborative environments. diff --git a/docs/tutorials/polykey-core/README.md b/docs/tutorials/polykey-core/README.md deleted file mode 100644 index d218cebf..00000000 --- a/docs/tutorials/polykey-core/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Core - - diff --git a/docs/tutorials/polykey-core/installation.md b/docs/tutorials/polykey-core/installation.md deleted file mode 100644 index 6e898ecc..00000000 --- a/docs/tutorials/polykey-core/installation.md +++ /dev/null @@ -1,118 +0,0 @@ -# Installation - -## Polykey Core - -The Polykey core contains the service, domain business logic and persistence -layers of Polykey. - -It is written in TypeScript and C++. - -The codebase is intended to be cross-platform, however it is currently only -tested on Linux. - -As a contributor, this would be your entrypoint to Polykey. - -:::caution - -At this point in time, the Polykey core library also contains all of the CLI -code. This means in order to use Polykey, you must use the Polykey core library. -We intend to extract out the CLI code, and move it into -[Polykey CLI](https://github.com/MatrixAI/Polykey-CLI). Once this is done, users -will not directly interact with the -[Polykey Core](https://github.com/MatrixAI/Polykey). Instead the core will just -be a dependency of the other projects. - -::: - -### Requirements - -- 64-bit Linux Operating System -- Node v16.15 or above and Node Package Manager -- Optionally `nix-shell` to setup development environment - -### Source Repository - -The official source repository is on GitHub. There is an additional mirror on -GitLab. - -```shell -git clone https://github.com/MatrixAI/Polykey.git -``` - -Use `npm install` to setup the project. - -:::tip - -If you have `nix-shell` available, enter into `nix-shell` and it will -automatically setup the develoment environment. - -::: - -### Node Package Manager - -The core library is published as -[`npm` package](https://www.npmjs.com/package/polykey). - -#### Global Package - -Install it with: - -```shell -npm install --location=global polykey -``` - -This will install the Polykey core library into `$(npm config get prefix)`. - -There will be 2 executables made available inside -`$(npm bin --location=global)`. - -For example on Ubuntu: - -```shell-session -$ tree "$(npm bin --location=global)" -/usr/local/bin/ -├── pk -> ../lib/node_modules/polykey/dist/bin/polykey.js -└── polykey -> ../lib/node_modules/polykey/dist/bin/polykey.js -``` - -If the `npm` bin path is added to the `$PATH` environment variable, then you -will be able to execute `pk` or `polykey`. - -#### Local Package - -Local installation is intended for downstream projects, where Polykey is -embedded as a JavaScript library. - -```shell -npm install polykey -``` - -Use the `npx polykey` or `npx pk` execute the local executables that are placed -in: - -```shell-session -$ tree ./node_modules/.bin -./node_modules/.bin/ -├── pk -> ../polykey/dist/bin/polykey.js -└── polykey -> ../polykey/dist/bin/polykey.js -``` - -### Bundled Executables - -The core library is also released as a bundled executable. This is intended for -users who do not have Node.js installed. - -Go to https://github.com/MatrixAI/Polykey/releases and download the relevant -asset. - -We currently bundle for these platforms: - -- linux-x64 - this should work for any Linux distribution that follows the - Filesystem Hierarchy Standard. -- win-x64 -- macos-x64 -- macos-arm64 - -:::caution - -Not all platfoms are supported currently. We have only tested on linux-x64. diff --git a/docs/tutorials/polykey-desktop/README.md b/docs/tutorials/polykey-desktop/README.md deleted file mode 100644 index b25b9fdd..00000000 --- a/docs/tutorials/polykey-desktop/README.md +++ /dev/null @@ -1,12 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Desktop - -[Polykey Desktop](https://github.com/MatrixAI/Polykey-Desktop) is the desktop -application providing a graphical user interface for interacting with the -Polykey network. It is still currently under development. As of now, there are -no tutorials for Polykey Desktop. - -Follow our development on [GitHub](https://github.com/MatrixAI/Polykey-Desktop). - - diff --git a/docs/tutorials/polykey-mobile/README.md b/docs/tutorials/polykey-mobile/README.md deleted file mode 100644 index 236e46a7..00000000 --- a/docs/tutorials/polykey-mobile/README.md +++ /dev/null @@ -1,12 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Mobile - -[Polykey Mobile](https://github.com/MatrixAI/Polykey-Mobile) is the mobile -application providing a graphical user interface for managing interactions with -the Polykey network from your mobile device. It is still currently under -development. As of now, there are no tutorials for Polykey Mobile. - -Follow our development on [GitHub](https://github.com/MatrixAI/Polykey-Mobile). - - diff --git a/sidebars.ts b/sidebars.ts index 8cceea87..a53815df 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -6,17 +6,13 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'Getting Started', collapsed: false, - link: { - type: 'doc', - id: 'tutorials/README', - }, items: [ { type: 'category', label: 'Polykey CLI', link: { type: 'doc', - id: 'tutorials/polykey-cli/README', + id: 'Getting-Started/polykey-cli/README', }, items: [ 'Getting-Started/polykey-cli/installation', @@ -29,34 +25,7 @@ const sidebars: SidebarsConfig = { 'Getting-Started/polykey-cli/managing-multiple-nodes', 'Getting-Started/polykey-cli/using-environment-variables', ], - }, - { - type: 'category', - label: 'Polykey Desktop', - link: { - type: 'doc', - id: 'tutorials/polykey-desktop/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Mobile', - link: { - type: 'doc', - id: 'tutorials/polykey-mobile/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Core', - link: { - type: 'doc', - id: 'tutorials/polykey-core/README', - }, - items: ['tutorials/polykey-core/installation'], - }, + }, ], }, { From d07f2ee54e0319b15f933d0c966f4b1b905daa02 Mon Sep 17 00:00:00 2001 From: Aryan Jassal Date: Mon, 14 Apr 2025 15:06:26 +1000 Subject: [PATCH 6/6] docs: updated managing secrets page fix: lint fix: spelling --- docs/Getting-Started/polykey-cli/README.md | 11 +- .../polykey-cli/bootstrapping.md | 7 +- .../claiming-digital-identities.md | 28 +-- .../polykey-cli/discovering-other-users.md | 14 +- .../polykey-cli/installation.md | 24 ++- .../polykey-cli/managing-multiple-nodes.md | 9 +- .../polykey-cli/managing-secrets.md | 200 ++++++++++-------- .../polykey-cli/managing-vaults.md | 1 + .../using-environment-variables.md | 4 +- docs/README.md | 18 +- .../reference/polykey-cli/commands/secrets.md | 14 +- 11 files changed, 183 insertions(+), 147 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/README.md b/docs/Getting-Started/polykey-cli/README.md index eb1d32ba..068d98e1 100644 --- a/docs/Getting-Started/polykey-cli/README.md +++ b/docs/Getting-Started/polykey-cli/README.md @@ -37,11 +37,10 @@ Polykey is continuously built and tested on: :::note Note - Polykey is currently in beta. Its interface is at various levels of -stability. So bear with us as we perfect its design. You can contribute by -discussing with us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue -tickets in the -[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). +Polykey is currently in beta. Its interface is at various levels of stability. +So bear with us as we perfect its design. You can contribute by discussing with +us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue tickets in the +[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). ::: @@ -53,7 +52,7 @@ Start your journey with Polykey by following the tutorials below in sequence: For a visual walkthrough, check out our [getting started demo video](https://vimeo.com/884649667) after installing -Polykey. +Polykey. ::: diff --git a/docs/Getting-Started/polykey-cli/bootstrapping.md b/docs/Getting-Started/polykey-cli/bootstrapping.md index e99e9a5d..acf35bea 100644 --- a/docs/Getting-Started/polykey-cli/bootstrapping.md +++ b/docs/Getting-Started/polykey-cli/bootstrapping.md @@ -26,13 +26,16 @@ key. :::note Note -Remember to keep your password in a secure location as you will need it each time you start the Polykey agent. +Remember to keep your password in a secure location as you will need it each +time you start the Polykey agent. ::: :::important -Bootstrapping also returns a **recovery code**. This code is required to recover a node with the same ID, so it is critical that you store it safely and securely. If lost, node identity recovery will not be possible. +Bootstrapping also returns a **recovery code**. This code is required to recover +a node with the same ID, so it is critical that you store it safely and +securely. If lost, node identity recovery will not be possible. ::: diff --git a/docs/Getting-Started/polykey-cli/claiming-digital-identities.md b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md index f84762bd..3d72a986 100644 --- a/docs/Getting-Started/polykey-cli/claiming-digital-identities.md +++ b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md @@ -1,4 +1,4 @@ -# Establishing Identity Linkages in Polykey +# Establishing Identity Linkages In Polykey, claiming a digital identity is a crucial step that allows users to establish their identity across various platforms and link these identities to @@ -8,7 +8,9 @@ cryptographic link to a publicly verifiable location. This tutorial will guide you through the steps to authenticate with GitHub and claim an identity using Polykey, enhancing security and streamlining identity -verification, making it easier for other users to discover and trust your nodes. Currently, we only support github as an identity provider, but we plan to add more in the future. +verification, making it easier for other users to discover and trust your nodes. +Currently, we only support github as an identity provider, but we plan to add +more in the future. ## Step 1: Authenticate with GitHub @@ -33,8 +35,8 @@ polykey identities authenticate :::note Note -Since Polykey currently only supports GitHub as an IdP, this is the -command that you will use to start the authentication process. +Since Polykey currently only supports GitHub as an IdP, this is the command that +you will use to start the authentication process. ```bash polykey identities authenticate github @@ -74,19 +76,19 @@ identityId maverick During the authentication process, here's what Polykey requests access to and why: -- **Currently: Create Gists:** Polykey creates a gist under your GitHub account containing - a cryptographic link. This link is a verifiable method that proves the - ownership of your GitHub identity to anyone checking your Polykey gestalt +- **Currently: Create Gists:** Polykey creates a gist under your GitHub account + containing a cryptographic link. This link is a verifiable method that proves + the ownership of your GitHub identity to anyone checking your Polykey gestalt graph. -:::note Note - **Future Plan: Read All User Profile Data:** This enables Polykey to access your profile - details, including your username, followers, and public repository data. This - information is used to ensure that the identity you claim corresponds - accurately to your public digital footprint, enhancing trust and verification. +**Future Plan: Read All User Profile Data:** This enables Polykey to access your +profile details, including your username, followers, and public repository data. +This information is used to ensure that the identity you claim corresponds +accurately to your public digital footprint, enhancing trust and verification. - ::: +::: #### Security and Privacy Considerations @@ -150,7 +152,7 @@ https://gist.github.com/my-github-username This gist contains the cryptographic link confirming that your Polykey identity is correctly linked to your GitHub profile. Viewing this gist ensures your claim -was successful and publicly verifiable. +was successful and publicly verifiable. :::note Note diff --git a/docs/Getting-Started/polykey-cli/discovering-other-users.md b/docs/Getting-Started/polykey-cli/discovering-other-users.md index 15e6d6d5..aed997c7 100644 --- a/docs/Getting-Started/polykey-cli/discovering-other-users.md +++ b/docs/Getting-Started/polykey-cli/discovering-other-users.md @@ -38,9 +38,10 @@ polykey identities discover ```bash polykey identities discover github.com:maverick ``` -:::note Note -This command adds the node associated with the GitHub username "maverick" to -your discovery queue, allowing you to initiate interactions with this user. + +:::note Note This command adds the node associated with the GitHub username +"maverick" to your discovery queue, allowing you to initiate interactions with +this user. ::: @@ -117,7 +118,8 @@ managed: - **Scan:** Allows the node to scan for vaults - **Notify:** Allows sending notifications about changes or updates. -- **Claim** Allows a different gstalt to claim the node +- **Claim** Allows a different gstalt to claim the node + #### Example Command to Set Permissions ```bash @@ -192,8 +194,8 @@ polykey identities list ### Trusting and Untrusting Nodes -You can explicitly trust or untrust individual nodes or entire gestalts to refine how notifications and -access controls are handled: +You can explicitly trust or untrust individual nodes or entire gestalts to +refine how notifications and access controls are handled: ```bash polykey identities trust diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 8b96e4fb..9802f831 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -6,13 +6,17 @@ Installing the CLI can be done in different ways depending on your operating environment. :::info + ## Polykey Core Overview -The Polykey CLI and core primarily use TypeScript for service logic, domain business operations, and persistence layers. While the main codebase is in TypeScript, some supporting libraries incorporate native C++ or Rust for platform‐specific functionality. This approach combines cross‐platform convenience with native performance optimizations. -Polykey-CLI has only been tested on Linux and macOS. We are working on -supporting other platforms. There's minor teething problems when it comes -supporting other platforms. Help us by reporting any issues with the CLI tool in -our Github Repo +The Polykey CLI and core primarily use TypeScript for service logic, domain +business operations, and persistence layers. While the main codebase is in +TypeScript, some supporting libraries incorporate native C++ or Rust for +platform‐specific functionality. This approach combines cross‐platform +convenience with native performance optimizations. Polykey-CLI has only been +tested on Linux and macOS. We are working on supporting other platforms. There's +minor teething problems when it comes supporting other platforms. Help us by +reporting any issues with the CLI tool in our Github Repo [here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping a message to the developers in our discord server [here](https://discord.gg/dC32r35TeE). @@ -134,9 +138,9 @@ We will be working on other distribution methods. :::info -ARM-64 builds are not currently supported on MacOS as of **6 April 2025.** However, -building Polykey yourself on MacOS resolves in a working binary. Follow this -guide below to manually build and install Polykey on macOS. +ARM-64 builds are not currently supported on MacOS as of **6 April 2025.** +However, building Polykey yourself on MacOS resolves in a working binary. Follow +this guide below to manually build and install Polykey on macOS. ::: @@ -290,7 +294,7 @@ echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc The path export should not pint to the Polykey executable itself, but rather to the directory containing the executable. Otherwise, the executable will not be -found and will not work. +found and will not work. ::: @@ -300,7 +304,7 @@ found and will not work. 2. Edit the Bash config to add "polykey" to your path. To streamline the process, run the following command, making sure to change the path to "polykey" if the executable is not in the downloads folder. For most users, - this would be `~/Downloads` + this would be `~/Downloads` :::tip diff --git a/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md index 36c537c4..9b614cbd 100644 --- a/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md +++ b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md @@ -2,7 +2,10 @@ Managing multiple local -nodes in Polykey can serve various purposes. For example, you might maintain one node for personal projects and another for professional work. This segregation ensures that the vaults and their respective contents remain distinct based on their usage context. +nodes in Polykey can serve various purposes. For example, you might maintain one +node for personal projects and another for professional work. This segregation +ensures that the vaults and their respective contents remain distinct based on +their usage context. This approach is particularly advantageous for demonstrations or training purposes, as it allows you to simulate sharing vaults between two nodes on the @@ -40,8 +43,8 @@ context. :::note Note - If a node has not been created before, initializing the Polykey agent -for it will also initiate the bootstrap process. +If a node has not been created before, initializing the Polykey agent for it +will also initiate the bootstrap process. ::: diff --git a/docs/Getting-Started/polykey-cli/managing-secrets.md b/docs/Getting-Started/polykey-cli/managing-secrets.md index 26712b73..443d04e1 100644 --- a/docs/Getting-Started/polykey-cli/managing-secrets.md +++ b/docs/Getting-Started/polykey-cli/managing-secrets.md @@ -7,11 +7,13 @@ such as API keys, configuration files, or documents. These can be any file type that you need to encrypt and manage securely. This section provides a detailed guide on how to manage these secrets within vaults using Polykey-CLI. -:::tip +:::tip Tip In the Polykey CLI, you can get help with managing your Secrets Operations by -using the `-help` help command to get a detailed list of availiable options and -commands. Try running `polykey secrets -help` ::: +using the `--help` help command to get a detailed list of availiable options and +commands. Try running `polykey secrets --help` + +::: ## Creating Secrets @@ -30,7 +32,7 @@ secret. specified as `:` - ::: +::: ### Adding a Secret to a Vault @@ -38,11 +40,15 @@ The `polykey secrets create` command clones an existing file from your local machine and stores it into an encrypted vault, creating a secret in the process. Thus, providing secure data-at-rest encryption of the file. -:::tip To create a secret, both the vault and file you are creating a secret -from, must already exist. Remember that to view the vaults contained within a -node, you run `polykey vaults list`. This is useful for viewing the names of -the vaults you are trying to manage secrets with, as vaultName is one of the -command arguments that is commonly used. ::: +:::tip Tip + +To create a secret, both the vault and file you are creating a secret from, must +already exist. Remember that to view the vaults contained within a node, you run +`polykey vaults list`. This is useful for viewing the names of the vaults you +are trying to manage secrets with, as vaultName is one of the command arguments +that is commonly used. + +::: #### Command Arguments @@ -50,15 +56,15 @@ command arguments that is commonly used. ::: polykey secrets create : ``` -:::info +:::info Info -The `` for the file you are trying to create a secret from can -either be a working directory filepath or a root path. Also notice that we -either have 1 space of seperation or a `:` between command arguments usually. +The `` for the file you are trying to create a secret from can either +be a working directory filepath or a root path. Also notice that we either have +1 space of seperation or a `:` between command arguments usually. ::: -#### Example Usage of `polykey secrets create` +#### Example usage ```bash polykey secrets create ./API_ACCESS_KEY.txt my-api-vault:API_ACCESS_KEY @@ -70,16 +76,22 @@ secretName alias as `API_ACCESS_KEY`. We could have also provided the secretName alias as `API.ACCESS_KEY.txt` but for most text files in Polykey, specifying the file type extension is redundant. -:::tip Since the secret or `` stored in the vault does not specify -the file type in its metadata, when you are storing binary files such as images -or videos, you may want to specify the file extension in the `secretName` alias -for better access & manageability. ::: +:::tip Tip + +Since the secret or `` stored in the vault does not specify the file +type in its metadata, when you are storing binary files such as images or +videos, you may want to specify the file extension in the `secretName` alias for +better access & manageability. + +::: ## Listing Secrets -:::note **List all Available Secrets for a Vault** +:::note Note -**Usage:** `polykey secrets list|ls [options] ` +**List all Available Secrets for a Vault** + +**Usage:** `polykey secrets ls|list [options] ` **Arguments:** @@ -90,44 +102,41 @@ for better access & manageability. ::: To list the secret file(s) stored within a specific vault in your default nodePath, use: -#### Command Arguments: +### Command Arguments: ```bash -polykey secrets list +polykey secrets ls ``` #### Example Usage -```bash -Polykey secrets list my-api-vault -``` - -#### Example Output - In this case, there's just one secret file contained in this vault, the secret we created in the previous example. ```bash +$ polykey secrets ls my-api-vault API_ACCESS_KEY ``` -:::note Secure Deletion of Local Secrets +:::tip Secure Deletion of Local Secrets After adding a secret to a vault, securely delete the local copy if it's no longer needed. This ensures that no unsecured traces of sensitive information -remain on your local filesystem. ::: +remain on your local filesystem. + +::: - Retreiving Secrets +## Retreiving Secrets Retrieve a secret from the given vault using the polykey secrets get command. This command accesses the encrypted content within a vault and outputs it, allowing for further handling depending on the file type. -:::note +:::note Note -Retrieve a Secret from the Given Vault +Retrieve a secret from the given vault -**Usage:** `polykey secrets get [options] ` +**Usage:** `polykey secrets cat [options] ` **Arguments:** @@ -149,7 +158,7 @@ The nature of the file affects how it is handled when retrieved: are binary files. These do not display readable content directly in the terminal and must be handled differently. -### Retrieving a Text File +### Retrieving a text file To view the contents of a text file stored in a vault directly from the terminal, use the following command: @@ -158,7 +167,7 @@ terminal, use the following command: polykey secrets cat : ``` -#### Example: Retrieving a Text File +#### Example Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault` @@ -170,7 +179,7 @@ AKfjd39jdi3903KDje93j04j0 This method displays text files directly in the terminal, providing immediate access to the contents. -### Retrieving Binary File +### Retrieving a binary file Binary files, such as images or executables, need to be handled appropriately to view or use their contents correctly. @@ -181,35 +190,33 @@ To retrieve and handle a binary file, specify the output format by redirecting the output to a file with the appropriate file extension: ```bash -polykey secrets get : > . - +polykey secrets cat : > . ``` This command saves the binary content into a file in the current local directory, preserving the file type as indicated by the extension ``. -#### Example: Retrieving and Viewing an Image +#### Example Retrieve an image stored in a vault and view it using system-specific commands: ```bash -$polykey secrets get my-NFT:Dali.png > Dali.png -$open Dali.png +$ polykey secrets cat my-NFT:Dali.png > Dali.png +$ open Dali.png ``` :::note Note -The use of `>` in the command line is a standard Unix redirection -operator, used here to direct the output from Polykey into a file. This -operation is necessary for handling binary files that require specific -applications to open. +The use of `>` in the command line is a standard Unix redirection operator, used +here to direct the output from Polykey into a file. This operation is necessary +for handling binary files that require specific applications to open. ::: :::tip Tip -Ensure the secret name includes the file extension (like Dali.png), which -helps clarify the file type when saving and accessing the retrieved file. +Ensure the secret name includes the file extension (like Dali.png), which helps +clarify the file type when saving and accessing the retrieved file. ::: @@ -223,14 +230,13 @@ vault. polykey secrets mkdir : ``` -:::note Example: Creating a Directory in a Vault +### Example To create a directory named "NFTs" within the "my-image-vault": ```bash polykey secrets mkdir my-image-vault:NFTs ``` -:::note ### Adding a Secret to a Directory in a Vault @@ -241,7 +247,7 @@ similar types of secrets under a common directory. polykey secrets create :/ ``` -#### Example: Adding a Secret to a Directory +#### Example To add the file "Dali.png" as a secret named "Dali.png" to the "NFTs" directory within "my-image-vault": @@ -250,20 +256,19 @@ within "my-image-vault": polykey secrets create ./Dali.png my-image-vault:NFTs/Dali.png ``` -:::note To view secrets saved within a directory in a vault, using the -`polykey secrets list ` command for that vault will output all -secrets in the vault, including those within directories. - -**Example Usage** +:::note Note -```bash - polykey secrets list my-image-vault -``` +To view secrets saved within a directory in a vault, using the +`polykey secrets ls ` command for that vault will output all secrets +in the directory, _not_ the entire vault. -**Output** +**Example Usage** ```bash -NFTs/Owner.png +$ polykey secrets ls my-image-vault +NFTs/ +$ polykey secrets ls my-image-vault:NFTs +NFTs/Dali.png ``` ::: @@ -276,26 +281,34 @@ To rename an existing secret: polykey secrets rename : ``` -:::tip Use the `secrets list` command to check on your renamed secretFile. ::: +:::tip Tip -### Updating a Secret +Use the `secrets ls` command to check on your renamed secretFile. + +::: + +## Updating a Secret To update the contents of an existing secret: ```bash -polykey secrets write : +polykey secrets write : ``` -#### Example: Secrets Update +### Example ```bash $ cat ./rare-dali.png | polykey secrets write my-image-vault:nfts/dali.png ``` -:::info This is essentially replacing the file content of an existing secret -while preserving the identity of the secret. One way to verify that the update -was performed sucesfully is by viewing the mtime (modified time) timestamp from -the `secrets stat` command. ::: +:::info Info + +This is essentially replacing the file content of an existing secret while +preserving the identity of the secret. One way to verify that the update was +performed sucesfully is by viewing the mtime (modified time) timestamp from the +`secrets stat` command. + +::: ## Retrieving Secret Metadata @@ -305,24 +318,33 @@ To view metadata about a secret: polykey secrets stat : ``` -:::note Note - -Example: Viewing Metadata for a Secret +### Example ```bash polykey secrets stat my-image-vault:NFTs/Dali.png ``` ```bash --> polykey nodes connections -host hostname nodeIdEncoded port timeout usageCount authenticated -13.210.66.119 N/A v8k5smi8a5o7j4mhdka50q679op9lctdcepgkuslrhumc0ur793og 1314 34004 0 false -2600:1f16:1f71:7c00:3593:3a22:674f:f33b N/A vair3u8kqfqoheulk277bp71j5vi80vd2bnavki02ekeounp72e80 1314 55884 0 false +$ polykey secrets stat myvault:file +dev 0 +ino 124 +mode 16877 +nlink 2 +uid 0 +gid 0 +rdev 0 +size 0 +atime Fri Aug 16 2024 16:55:58 GMT+1000 (Australian Eastern Standard Time) +mtime Mon Aug 19 2024 12:21:30 GMT+1000 (Australian Eastern Standard Time) +ctime Mon Aug 19 2024 12:21:30 GMT+1000 (Australian Eastern Standard Time) +birthtime Fri Aug 16 2024 16:55:58 GMT+1000 (Australian Eastern Standard Time) +blksize 0 +blocks 0 ``` :::note -### Understanding Metadata Terms +**Understanding Metadata Terms** - **dev:** Device number on which the file resides. - **ino:** File's inode number. @@ -349,29 +371,29 @@ To remove a secret from a vault: polykey secrets rm : ``` -:::note Note - Example: Deleting a Secret +### Example +```bash $ polykey secrets ls my-image-vault:nfts nfts/dali.png nfts/some-image.png - $ polykey secrets rm my-image-vault:nfts/some-image.png - -Note the lack of output - -:::note - +# Note the lack of output $ polykey secrets ls my-image-vault:nfts nfts/dali.png +``` -## Editing Secrets in a Vault +## Editing Secrets -To edit a secret directly within a Vault using Polykey: +To edit a secret directly within a vault using Polykey: ```bash polykey secrets edit : ``` -:::warning Polykey Secrets Edit on Mac OS has a bug that we are investigating. -Use Polykey Secrets Update in the meantime. ::: +:::warning Warning + +The command `polykey secrets edit` on MacOS has a bug that we are investigating. +Use `polykey secrets update` in the meantime. + +::: diff --git a/docs/Getting-Started/polykey-cli/managing-vaults.md b/docs/Getting-Started/polykey-cli/managing-vaults.md index 8f412ba7..3d02cc01 100644 --- a/docs/Getting-Started/polykey-cli/managing-vaults.md +++ b/docs/Getting-Started/polykey-cli/managing-vaults.md @@ -67,6 +67,7 @@ This operation does not produce output on successful execution, indicating the vault has been removed. :::note + ## Viewing Vault History Each vault maintains a version history which tracks changes over time. Use the diff --git a/docs/Getting-Started/polykey-cli/using-environment-variables.md b/docs/Getting-Started/polykey-cli/using-environment-variables.md index e055a10f..0ad7ffac 100644 --- a/docs/Getting-Started/polykey-cli/using-environment-variables.md +++ b/docs/Getting-Started/polykey-cli/using-environment-variables.md @@ -1,4 +1,4 @@ -# Using Environment Variables with Polykey +# Using Environment Variables Polykey revolutionizes the management of environment variables by injecting them securely into applications, surpassing traditional `.env` file methods. This @@ -59,7 +59,7 @@ application, you can output them in different formats. #### Unix-like Systems Example ```bash -olykey secrets env --env-format unix --env MyVault:API_KEY +polykey secrets env --env-format unix --env MyVault:API_KEY API_KEY=someRandomValue123 ``` diff --git a/docs/README.md b/docs/README.md index a44de42e..fc2fda84 100644 --- a/docs/README.md +++ b/docs/README.md @@ -71,22 +71,22 @@ passwords or keys. For this reason, we think of secrets as "capabilities". -All secrets are put into vaults. Each vault is a persistent, fully encrypted virtual -filesystem with automatic version history. Vaults can be shared with other -Polykey agents. +All secrets are put into vaults. Each vault is a persistent, fully encrypted +virtual filesystem with automatic version history. Vaults can be shared with +other Polykey agents. -Polykey's secrets management system provides users with secure communication -and secure computation. +Polykey's secrets management system provides users with secure communication and +secure computation. ### Decentralized Trust -Sharing secrets depends on secure communications. Secure communications depends on -trusted identities. +Sharing secrets depends on secure communications. Secure communications depends +on trusted identities. Polykey introduces a concept called "Gestalt Identity". -A Gestalt Identity is a collection of digital identities (i.e. social media profiles -and Polykey nodes) that all represent the same entity. +A Gestalt Identity is a collection of digital identities (i.e. social media +profiles and Polykey nodes) that all represent the same entity. When you start a Polykey agent, it immediately forms its own gestalt with the Polykey node as its only identity. Link up your digital identities to the node diff --git a/docs/reference/polykey-cli/commands/secrets.md b/docs/reference/polykey-cli/commands/secrets.md index 4f903f7b..2594e06e 100644 --- a/docs/reference/polykey-cli/commands/secrets.md +++ b/docs/reference/polykey-cli/commands/secrets.md @@ -67,7 +67,7 @@ $ polykey secrets dir ~/test-dir vault1 :::warning Warning -This command does not work on Windows yet +This command does not work on Windows yet ::: @@ -89,9 +89,9 @@ I edited this secret inside an editor 4. If no paths are specified, this command takes input from `stdin` and prints it to `stdout` -:::tip Tip +:::tip Tip -`^D` in the terminal stands for the key combination 'Ctrl-D' +`^D` in the terminal stands for the key combination 'Ctrl-D' ::: @@ -194,7 +194,7 @@ new-name :::note Note - The mode (or file permissions) doesn't exist within a vault +The mode (or file permissions) doesn't exist within a vault ::: @@ -270,11 +270,11 @@ do not commit your keys to github :::tip Tip -`stdin`, or standard input, can be either manually entered by typing, or -piped in through another command. +`stdin`, or standard input, can be either manually entered by typing, or piped +in through another command. To close the input steam and save the file, press `^D`, or 'Ctrl-D' in a new -line, or press `^D` twice on the same line. +line, or press `^D` twice on the same line. :::