diff --git a/docs/README.md b/docs/README.md index f2163de6..375d8da8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,16 +5,25 @@ displayed_sidebar: docs # Polykey Documentation -Welcome to the Polykey documentation. + -- [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 achieve a specific use-case which makes assumptions on the reader -- [Theory](./theory/) - these are important for understanding the "why" of Polykey -- [Reference](./reference/) - these are useful when you need remember how to use a particular command or function + + + ## Introduction @@ -30,10 +39,6 @@ Polykey helps yourself, teams and software agents to manage and share secrets in PolyKey is an open-source decentralised peer to peer secrets management system. It provides a software agent that runs on your device locally. Each agent process is a node in the Polykey peer to peer network. This agent manages your secret data and is capable of sharing secrets with other trusted Polykey agents. The secret data can be placed inside any directory on your computer including on USB storage. -## Features - -TBD - ## Principles There are 2 main concepts to understand in Polykey: @@ -71,6 +76,38 @@ As you deploy more Polykey agents, you can join existing gestalts. Your gestalt is how other users are able to share secrets with a trusted identity. Your identity is the sum of the reputation of all your digital identities that are part of the gestalt. -## Comparison to other Tools + + + diff --git a/docs/getting-started/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md new file mode 100644 index 00000000..2412f66d --- /dev/null +++ b/docs/getting-started/claiming-digital-identities.md @@ -0,0 +1,107 @@ +# Claim Your Digital Identity + +This guide demonstrates how to link your Polykey node to a GitHub identity, enhancing discoverability and trust within the network. + +
+Why Link a GitHub Identity? +Linking your Polykey node to GitHub improves discoverability and simplifies trust-building within the network by providing a familiar and verifiable identity. +
+ +## Prerequisites + +- Your default Polykey node must be installed and operational. +- Have access to your GitHub credentials. + +
+Handled Data and Privacy + +- **Technical Use of Permissions**: During the authentication process, Polykey requests access to create gists, read all user profile data, and access user email addresses (read-only) to ensure accurate identity verification and manage notifications. + +- **Security and Privacy Considerations**: Polykey adheres to high standards of security and privacy, using accessed data strictly for mentioned operations and not sharing it with third parties. For more details, refer to our [privacy policy](https://polykey.com/privacy-policy). +
+ +## Step 1: Authenticate with GitHub + +Initiate authentication with GitHub to allow your node to access necessary identity information. + +```pkcli +polykey identities authenticate github.com +``` + +:::tip + +Follow the terminal prompts to log into GitHub and authorize Polykey to access your information. + +::: + +![GitHub Authentication](/images/github-authentication.png) + +## Step 2: Claim Your Identity + +Link your GitHub identity with your Polykey node to establish a verifiable identity connection. + +```pkcli +polykey identities claim github.com: +``` + +:::tip +Replace `my-gh-username` with your actual GitHub username. +::: + +Cryptolink + +## Step 3: Verify Your Claim + +Check the link to the GitHub gist provided by Polykey to verify your identity claim. + +![Claim Id](/images/claim-id.png) +:::note +Visit the gist URL to ensure it exists and is correct. +::: + +## Understanding the Impact + +Claiming a GitHub identity creates a gestalt graph that enhances the discoverability of your node. + +![gestalts](/images/gestalts.png) + +
+Learn More About Gestalt Graphs + +### Understanding Gestalt Graphs + +**Gestalt Graphs** are visual representations of the relationships and trust connections between different digital identities within Polykey. Each node on a graph symbolizes an identity or a claim, and the edges between nodes represent cryptographic verifications or trust relationships. + +#### How Gestalt Graphs Work + +- **Nodes**: Represent individual identities linked to Polykey, such as a GitHub username. +- **Edges**: Signify the trust connections or verification links between various identities. + +As you expand your digital presence by claiming more identities, or by adding more nodes to your network, the gestalt graph grows accordingly. This dynamic expansion enhances the network's utility by streamlining the process of identity verification and making the establishment of trust relationships more transparent and traceable. + +#### Claiming Multiple Identities + +Polykey allows for flexible management of digital identities, accommodating multiple use cases: + +- **Multiple IdPs for a Single Node**: You can link one Polykey node to several identity providers, enhancing your digital verification pathways and security. +- **Single IdP Across Multiple Nodes**: Claim and link the same identity provider, like a GitHub username, across multiple Polykey nodes you control, thus broadening your digital identity and reach within the network. + +#### Future Plans and IdP Support + +Currently, Polykey integrates with GitHub as a primary identity provider. Our ongoing development aims to broaden this integration to include various major identity providers (IdPs), significantly enhancing accessibility and user engagement. Future updates will also allow organizations to implement their own IdPs, offering even greater control and customization of identity management operations within Polykey. + +#### Benefits of Federated Identities + +Adopting a federated identity model through gestalt graphs provides several advantages: + +- **Enhanced Security**: Links multiple identity proofs to fortify the authenticity and credibility of your digital identity. +- **Simplified Identity Management**: Manages multiple identities through a unified interface, reducing complexity and streamlining user interactions. +- **Interoperability**: Facilitates seamless interactions across different platforms and services, leveraging a cohesive identity framework. + +Utilizing gestalt graphs within Polykey enhances operational security and simplifies digital identity management, making it an indispensable tool for users navigating complex digital environments. + +
+ +## Conclusion + +Linking your GitHub identity with Polykey enhances both security and usability, making your digital interactions within the network more seamless and verifiable. diff --git a/docs/tutorials/polykey-cli/installation.md b/docs/getting-started/installing-polykey-cli.md similarity index 59% rename from docs/tutorials/polykey-cli/installation.md rename to docs/getting-started/installing-polykey-cli.md index f477832c..62d1466b 100644 --- a/docs/tutorials/polykey-cli/installation.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -1,20 +1,59 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Installation +# Set-Up Polykey on your Machine -Installing the CLI can be done in different ways depending on your operating environment. +:::note +The Polykey Command Line Interface (CLI) is the primary user interface for the Polykey system. It is designed to be human-operable and easily scriptable for integration into other tools. It targets developers and system administrators who need an advanced tool for efficient secrets management. +::: + +## Choose Your Installation Method for the Polykey-CLI + + + + + +### Install using Node Package Manager + +The Polykey CLI is available as an [`npm` package](https://www.npmjs.com/package/polykey-cli). This method facilitates easy installation across different operating systems using Node.js and npm. :::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). +#### System Requirements + +Before installing, ensure your system meets the following criteria: + +- **Node.js**: Install the latest stable version from [nodejs.org](https://nodejs.org). +- **npm (Node Package Manager)**: Ensure it is up to date by running `npm install -g npm` in your terminal. +- **Environment Variables**: Add the `npm` binary path to your system’s `$PATH` to execute Polykey CLI commands from any terminal window. ::: +#### Install Command + +To install the Polykey CLI globally on your system, use the following command: + +```sh +npm install -g polykey-cli +``` + +:::note +This installs the Polykey CLI globally, allowing you to use `pk` or `polykey` commands from any directory. +::: + + + + + +### Install Manually + +Choose your operating system below to view specific installation instructions. + - -## Linux + + +#### Linux Installation 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. @@ -25,7 +64,7 @@ Polykey-CLI code is compiled, bundled and wrapped into a single file executable. - `libpthread.so.0` - `libc.so.6` -### Manually +##### Manually Builds for Linux is released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases. @@ -37,9 +76,9 @@ Make it executable: chmod u+x ./polykey ``` -### Add it to your `$PATH`. +#### Add it to your `$PATH`. -#### For ZSH: +##### 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. @@ -59,7 +98,7 @@ You can now run it with `polykey`. --- -#### For Bash: +##### For Bash: 1. If you're using Bash, run the following command to add polykey to your path. Ensure to change the path if the executable is not in the downloads folder. For most users, this would be `~/downloads` on Debian-based systems. @@ -77,7 +116,7 @@ You can now run it with `polykey`. --- -### NixOS +#### NixOS We have not yet published a Nixpkgs expression for Polykey. When we do, you will be able to just install `polykey-cli` from Nixpkgs. @@ -101,14 +140,14 @@ Build the application and install it into the user profile: nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)" ``` -### Other +#### Other We will be working on other distribution methods. -## MacOS +#### MacOS :::info @@ -117,7 +156,7 @@ However, building Polykey yourself on MacOS resolves in a working binary. Follow ::: -### Manually +#### 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. @@ -142,7 +181,7 @@ chmod +x polykey --- -### MacOS Security Bypass +#### 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, @@ -151,7 +190,8 @@ and MacOS permits running of unsigned binaries, however, to progress past this, - #### Method #1 - quickest method +##### 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 @@ -167,7 +207,7 @@ If you have completed this sucesfully, you may ignore Method #2 and move to the -#### Method #2 - Using the Apple Systems Settings GUI +##### 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. @@ -203,7 +243,7 @@ When prompted in the terminal, type your administrator password and hit enter. ![install3](/images/mac-install3.png) -#### Click on Open and now Polykey-CLI should be running in your terminal window. +##### 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: @@ -219,14 +259,14 @@ You can also verify the version of polykey that was installed with: -### Add Polykey to your `$PATH`. +#### 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): +##### For ZSH (default shell on recent macOS versions): 1. Navigate (cd) into the directory where the "polykey" executable is stored. @@ -245,7 +285,7 @@ echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc -#### For Bash: +##### 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. @@ -285,9 +325,14 @@ Polykey for windows should be working but we have yet to create documentation on ::: - - ## Docker + + + + + + +## Installing PK CLI on 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. @@ -367,42 +412,165 @@ recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly ``` - - + -## Node Package Manager + -The CLI is published as [`npm` package](https://www.npmjs.com/package/polykey-cli). +--- -Install it with: +## Bootstrapping Your First Node -```sh -npm install -g polykey-cli +:::note +Bootstrapping is the process for setting up a new Polykey node. This involves generating a key pair, creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. +::: + +### 1. Start the Polykey Agent + +To start the Polykey agent in the background, run the following command: + +```pkcli +polykey agent start --background ``` -This will install the Polykey-CLI into `$(npm config get prefix)`. +
+ Options for Starting the Polykey Agent -If the `npm` bin path is added to the `$PATH` environment variable, then you will be able to execute `pk` or `polykey`. +:::info - - +#### Starting the polykey agent in the Foreground vs. the Background -## Source +In this guide, we recommend starting the Polykey agent with the `--background` option because it allows the agent to run without occupying a terminal window, enabling you to use the shell for other commands. -The official source repository is on GitHub. There is an additional mirror on GitLab. +However, for monitoring network activity and debugging, running the Polykey agent in the foreground can be beneficial. To do this, execute the command without the `--background` option: -```shell -git clone https://github.com/MatrixAI/Polykey-CLI.git +```pkcli +polykey agent start ``` -Use `npm install` to setup the project. +This will display real-time network connections and is particularly useful for observing the interactions between your node and seed nodes within the network. It also facilitates capturing error logs or unusual activity, which can be crucial for reporting issues. For verbose output, include the `--verbose` option: -:::tip +```pkcli +polykey agent start --verbose +``` -If you have `nix-shell` available, enter into `nix-shell` and it will automatically setup the development environment. +#### Default Node Bootstrapping and the `--node-path` Option + +When you start the Polykey agent for the first time without specifying a node path, it automatically initializes using the default node path. This is convenient for quickly setting up a node: + +```pkcli +polykey agent start +``` + +If you wish to manage multiple nodes or specify a custom path for your node's data, you can use the `--node-path` option. This is necessary for targeting operations at a node located outside the default path. For example, to start an agent for a node in a custom directory, you would use: + +```pkcli +polykey bootstrap --node-path /custom/node/path +``` + +Then to start the Polykey agent for operating on the custom node, you would run: + +```pkcli +polykey agent start --node-path /custom/node/path +``` + +The same applies to any other Polykey commands that you wish to target the custom node. ::: - +
- +### 2. Create & Confirm Your Password + +:::note + +When prompted, create a **new password** for your default node. Confirm the password to generate a node with a unique **nodeId** and **recoveryCode**. + +:::warning +You will need to enter this password every time you start the Polykey agent for your default node. Ensure you remember it to access your node. +::: + +![pk-agent-start-bkg-bootstrap.png](/images/pk-agent-start-bkg-bootstrap.png) + +### 3. Verify the status of your PK agent + +To check the status of your Polykey agent, run: + +```pkcli +polykey agent status +``` + +:::info + +This command provides detailed information about your node's current state, including its **nodeId**, connectivity status, and any running processes. + +![pk-agent-status.png](/images/pk-agent-status.png) + +:::note + +If you have reached this step, you have successfully bootstrapped your first node on Polykey! + +::: + +### 4. Explore Polykey using the CLI's Helper + +To explore the available primary commands and get more detailed help, use: + +```pkcli +polykey --help +``` + +![pk-help.png](/images/pk-help.png) + +:::tip Use the CLI Helper Effectively + +- To list all sub-commands available for a primary command, type: + +```pkcli +polykey [primary command] --help +``` + +- For detailed information on a specific sub-command, type: + +```pkcli +polykey [primary command] [sub-command] --help +``` + +These commands provide you with helpful guidance on using different functionalities within Polykey. + +::: + +### 5. Stopping the Polykey Agent + +To stop the Polykey agent, use: + +```pkcli +polykey agent stop +``` + +### Troubleshooting + +:::info + +#### Issues with Starting the Polykey Agent: + +- **Check for Existing Agent Instances:** Before starting a new agent, ensure there isn't already one running by executing: + +```pkcli +polykey agent status +``` + +#### Issues with Stopping the Polykey Agent: + +- **Force Termination:** If the Polykey agent does not terminate properly, use Activity Monitor (macOS), Task Manager (Windows), or system monitor tools (Linux) to forcefully end the process. + +#### Errors on Agent Start: + +- **Seek Help:** If your Polykey agent fails to start due to an error, please reach out on our [Discord Server](https://discord.gg/vfXQZwwugc) and [submit a bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=) detailing the issue. + +To assist in diagnosing the issue, please include the verbose output from your terminal. Run the Polykey agent with the verbose flag: + +```pkcli +polykey agent start --verbose +``` + +::: diff --git a/docs/tutorials/polykey-cli/README.md b/docs/getting-started/polykey-cli/README.md similarity index 64% rename from docs/tutorials/polykey-cli/README.md rename to docs/getting-started/polykey-cli/README.md index c254b95b..43fb16a2 100644 --- a/docs/tutorials/polykey-cli/README.md +++ b/docs/getting-started/polykey-cli/README.md @@ -35,15 +35,15 @@ 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. ::: -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. +1. **[Installation](/docs/getting-started/polykey-cli/installation)** - Install Polykey CLI on your platform. +2. **[Bootstrap Keypair](/docs/getting-started/polykey-cli/bootstrapping)** - Set up your node and connect to the network. +3. **[Managing Vaults](/docs/getting-started/polykey-cli/managing-vaults)** - Securely store secrets within encrypted vaults. +4. **[Managing Secrets](/docs/getting-started/polykey-cli/managing-secrets)** - Organize and handle secrets within your vaults. +5. **[Claiming Digital Identities](/docs/getting-started/polykey-cli/claiming-digital-identities)** - Establish and authenticate your identity within the network. +6. **[Discovering Other User's Identities](/docs/getting-started/polykey-cli/discovering-other-users)** - Find and verify other users to manage permissions. +7. **[Sharing Vaults](/docs/getting-started/polykey-cli/sharing-vaults)** - Share your encrypted vaults securely with peers. +8. **[Managing Multiple Nodes](/docs/getting-started/polykey-cli/managing-multiple-nodes)** - Operate multiple local nodes/agents. +9. **[Using Environment Variables](/docs/getting-started/polykey-cli/using-environment-variables)** - Master `polykey secrets env` for dynamic environment management. Explore advanced scenarios in subsequent sections, including: diff --git a/docs/tutorials/polykey-cli/bootstrapping.md b/docs/getting-started/polykey-cli/bootstrapping.md similarity index 100% rename from docs/tutorials/polykey-cli/bootstrapping.md rename to docs/getting-started/polykey-cli/bootstrapping.md diff --git a/docs/tutorials/polykey-cli/discovering-other-users.md b/docs/getting-started/polykey-cli/discovering-other-users.md similarity index 100% rename from docs/tutorials/polykey-cli/discovering-other-users.md rename to docs/getting-started/polykey-cli/discovering-other-users.md diff --git a/docs/tutorials/polykey-cli/managing-multiple-nodes.md b/docs/getting-started/polykey-cli/managing-multiple-nodes.md similarity index 100% rename from docs/tutorials/polykey-cli/managing-multiple-nodes.md rename to docs/getting-started/polykey-cli/managing-multiple-nodes.md diff --git a/docs/tutorials/polykey-cli/managing-secrets.md b/docs/getting-started/polykey-cli/managing-secrets.md similarity index 100% rename from docs/tutorials/polykey-cli/managing-secrets.md rename to docs/getting-started/polykey-cli/managing-secrets.md diff --git a/docs/tutorials/polykey-cli/managing-vaults.md b/docs/getting-started/polykey-cli/managing-vaults.md similarity index 100% rename from docs/tutorials/polykey-cli/managing-vaults.md rename to docs/getting-started/polykey-cli/managing-vaults.md diff --git a/docs/tutorials/polykey-cli/sharing-vaults.md b/docs/getting-started/polykey-cli/sharing-vaults.md similarity index 100% rename from docs/tutorials/polykey-cli/sharing-vaults.md rename to docs/getting-started/polykey-cli/sharing-vaults.md diff --git a/docs/tutorials/polykey-cli/using-environment-variables.md b/docs/getting-started/polykey-cli/using-environment-variables.md similarity index 100% rename from docs/tutorials/polykey-cli/using-environment-variables.md rename to docs/getting-started/polykey-cli/using-environment-variables.md diff --git a/docs/tutorials/polykey-core/README.md b/docs/getting-started/polykey-core/README.md similarity index 100% rename from docs/tutorials/polykey-core/README.md rename to docs/getting-started/polykey-core/README.md diff --git a/docs/tutorials/polykey-core/installation.md b/docs/getting-started/polykey-core/installation.md similarity index 100% rename from docs/tutorials/polykey-core/installation.md rename to docs/getting-started/polykey-core/installation.md diff --git a/docs/reference/polykey-desktop/README.md b/docs/reference/polykey-desktop/README.md deleted file mode 100644 index c32c68e1..00000000 --- a/docs/reference/polykey-desktop/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey-Desktop - - diff --git a/docs/reference/polykey-mobile/README.md b/docs/reference/polykey-mobile/README.md deleted file mode 100644 index cd37bc93..00000000 --- a/docs/reference/polykey-mobile/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey-Mobile - - 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/claiming-digital-identities.md b/docs/tutorials/polykey-cli/claiming-digital-identities.md deleted file mode 100644 index 655e2854..00000000 --- a/docs/tutorials/polykey-cli/claiming-digital-identities.md +++ /dev/null @@ -1,152 +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-desktop/README.md b/docs/tutorials/polykey-desktop/README.md deleted file mode 100644 index af7d379c..00000000 --- a/docs/tutorials/polykey-desktop/README.md +++ /dev/null @@ -1,9 +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 698807cd..00000000 --- a/docs/tutorials/polykey-mobile/README.md +++ /dev/null @@ -1,9 +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/docusaurus.config.ts b/docusaurus.config.ts index ae6fe883..c2803dfa 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -4,10 +4,6 @@ import type { Options as PluginGTagOptions } from '@docusaurus/plugin-google-gta import type { Options as ThemeOptions } from '@docusaurus/theme-classic'; import type { UserThemeConfig } from '@docusaurus/theme-common'; import { visit } from 'unist-util-visit'; -import { themes as prismThemes } from 'prism-react-renderer'; - -const lightCodeTheme = prismThemes.github; -const darkCodeTheme = prismThemes.dracula; /** * Docusaurus does not process JSX `` URLs @@ -65,7 +61,8 @@ const pluginTheme: [string, ThemeOptions] = [ const themeConfig: UserThemeConfig = { colorMode: { - disableSwitch: true, + defaultMode: 'light', + // DisableSwitch: false, }, navbar: { logo: { @@ -213,9 +210,9 @@ const themeConfig: UserThemeConfig = { copyright: `Copyright © ${new Date().getFullYear()} Matrix AI`, }, prism: { - theme: lightCodeTheme, - darkTheme: darkCodeTheme, - additionalLanguages: ['shell-session'], + additionalLanguages: ['shell-session', 'bash'], + theme: require('./src/css/custom-prism-theme.ts'), + darkTheme: require('./src/css/dark-custom-prism-theme.ts'), }, }; diff --git a/images/pk-agent-start-bkg-bootstrap.png b/images/pk-agent-start-bkg-bootstrap.png new file mode 100644 index 00000000..f7831a1c --- /dev/null +++ b/images/pk-agent-start-bkg-bootstrap.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9316b4698c38e4e769b445ff374b413f5e60ff1316305373f8e74e280dab2c0f +size 718234 diff --git a/images/pk-agent-status.png b/images/pk-agent-status.png new file mode 100644 index 00000000..e52a0405 --- /dev/null +++ b/images/pk-agent-status.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bbd69c54f8f810b9144a1d85f45ad6b0b7ee824742a214f740d012898ae99167 +size 116073 diff --git a/images/pk-help.png b/images/pk-help.png new file mode 100644 index 00000000..7cc55e69 --- /dev/null +++ b/images/pk-help.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f19eb33a63ada3294002c69220e5e19971374fa3af44ae1a13b348b1d085ce6d +size 654214 diff --git a/sidebars.ts b/sidebars.ts index 7b251807..7a06952d 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -4,58 +4,42 @@ const sidebars: SidebarsConfig = { docs: [ { type: 'category', - label: 'Tutorials', + label: 'Getting Started', collapsed: false, - link: { - type: 'doc', - id: 'tutorials/README', - }, items: [ + { + type: 'doc', + id: 'README', // This should match the path to your symlink + label: 'Welcome to Polykey', // Label for the sidebar item + }, + 'getting-started/installing-polykey-cli', + 'getting-started/claiming-digital-identities', + { type: 'category', label: 'Polykey CLI', link: { type: 'doc', - id: 'tutorials/polykey-cli/README', + id: 'getting-started/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/bootstrapping', + 'getting-started/polykey-cli/managing-vaults', + 'getting-started/polykey-cli/managing-secrets', + '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', ], }, - { - 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', + id: 'getting-started/polykey-core/README', }, - items: ['tutorials/polykey-core/installation'], + items: ['getting-started/polykey-core/installation'], }, ], }, @@ -152,24 +136,6 @@ const sidebars: SidebarsConfig = { }, ], }, - { - type: 'category', - label: 'Polykey-Desktop', - link: { - type: 'doc', - id: 'reference/polykey-desktop/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey-Mobile', - link: { - type: 'doc', - id: 'reference/polykey-mobile/README', - }, - items: [], - }, { type: 'category', label: 'Polykey-Core', diff --git a/src/css/custom-prism-theme.ts b/src/css/custom-prism-theme.ts new file mode 100644 index 00000000..10b1e51f --- /dev/null +++ b/src/css/custom-prism-theme.ts @@ -0,0 +1,73 @@ +import type { PrismTheme } from 'prism-react-renderer'; + +// To see changes in development restart docusaurus + +const theme: PrismTheme = { + plain: { + color: '#F8F8F2', + backgroundColor: '#282A36', + }, + styles: [ + { + types: ['prolog', 'constant', 'builtin'], + style: { + color: 'rgb(189, 147, 249)', + }, + }, + { + types: ['inserted', 'function'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['deleted'], + style: { + color: 'rgb(255, 85, 85)', + }, + }, + { + types: ['changed'], + style: { + color: 'rgb(255, 184, 108)', + }, + }, + { + types: ['punctuation', 'symbol'], + style: { + color: 'rgb(248, 248, 242)', + }, + }, + { + types: ['string', 'char', 'tag', 'selector'], + style: { + color: 'rgb(255, 121, 198)', + }, + }, + { + types: ['keyword', 'variable'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['command'], + style: { + color: 'rgb(167, 199, 231)', + }, + }, + { + types: ['comment'], + style: { + color: 'rgb(98, 114, 164)', + }, + }, + { + types: ['attr-name'], + style: { + color: 'rgb(241, 250, 140)', + }, + }, + ], +}; +export default theme; diff --git a/src/css/dark-custom-prism-theme.ts b/src/css/dark-custom-prism-theme.ts new file mode 100644 index 00000000..bf2c78cb --- /dev/null +++ b/src/css/dark-custom-prism-theme.ts @@ -0,0 +1,73 @@ +import type { PrismTheme } from 'prism-react-renderer'; + +// To see changes in development restart docusaurus + +const darkTheme: PrismTheme = { + plain: { + color: '#F8F8F2', + backgroundColor: '#282A36', + }, + styles: [ + { + types: ['prolog', 'constant', 'builtin'], + style: { + color: 'rgb(189, 147, 249)', + }, + }, + { + types: ['inserted', 'function'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['deleted'], + style: { + color: 'rgb(255, 85, 85)', + }, + }, + { + types: ['changed'], + style: { + color: 'rgb(255, 184, 108)', + }, + }, + { + types: ['punctuation', 'symbol'], + style: { + color: 'rgb(248, 248, 242)', + }, + }, + { + types: ['string', 'char', 'tag', 'selector'], + style: { + color: 'rgb(255, 121, 198)', + }, + }, + { + types: ['keyword', 'variable'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['command'], + style: { + color: 'rgb(0, 199, 231)', + }, + }, + { + types: ['comment'], + style: { + color: 'rgb(98, 114, 164)', + }, + }, + { + types: ['attr-name'], + style: { + color: 'rgb(241, 250, 140)', + }, + }, + ], +}; +export default darkTheme; diff --git a/src/prism/custom-cli.js b/src/prism/custom-cli.js new file mode 100644 index 00000000..246f5cfc --- /dev/null +++ b/src/prism/custom-cli.js @@ -0,0 +1,30 @@ +import { Prism } from 'prism-react-renderer'; + +Prism.languages.pkcli = { + comment: { + pattern: /#.*/, + greedy: true, + }, + keyword: + /\b(?:vaults|create|list|delete|log|rename|list|-h|secrets|get|update|agent|start|status|stop|identities|authenticate|stat)\b/, + command: { + pattern: /(^\s*|\s+)(polykey)(?=\s|$)/, + lookbehind: true, + }, + parameter: { + pattern: /--?\w+/, + alias: 'operator', + }, + string: { + pattern: /("|')(?:\\.|(?!\1)[^\\\r\n])*\1/, + greedy: true, + }, + function: { + pattern: /\b\w+(?=\()/, + alias: 'function', + }, + number: { + pattern: /\b\d+(?:\.\d+)?\b/, + alias: 'number', + }, +}; diff --git a/src/theme/prism-include-languages.js b/src/theme/prism-include-languages.js new file mode 100644 index 00000000..d293e534 --- /dev/null +++ b/src/theme/prism-include-languages.js @@ -0,0 +1,26 @@ +import siteConfig from '@generated/docusaurus.config'; +export default function prismIncludeLanguages(prismObject) { + const { + themeConfig: { prism }, + } = siteConfig; + const { additionalLanguages } = prism; + // Prism components work on the Prism instance on the window, while prism- + // react-renderer uses its own Prism instance. We temporarily mount the + // instance onto window, import components to enhance it, then remove it to + // avoid polluting global namespace. + // You can mutate PrismObject: registering plugins, deleting languages... As + // long as you don't re-assign it + globalThis.Prism = prismObject; + additionalLanguages.forEach((lang) => { + if (lang === 'php') { + // eslint-disable-next-line global-require + require('prismjs/components/prism-markup-templating.js'); + } + + // eslint-disable-next-line global-require, import/no-dynamic-require + require(`prismjs/components/prism-${lang}`); + }); + require('@site/src/prism/custom-cli.js'); + + delete globalThis.Prism; +}