Merge pull request #75 from MatrixAI/feature-getting-started-finalized

Polykey-Docs: Complete V1 of Polykey-CLI Tutorials

Author: CryptoTotalWar

docs/tutorials/polykey-cli/README.md

@@ -14,12 +14,12 @@ The tutorial here should be followed in order, and the goal is to make use of Po
 
 The CLI is open-source and available on GitHub: [Polykey CLI](https://github.com/MatrixAI/Polykey-CLI).
 
-We automatically build and test the CLI on the following platforms:
+### Supported Platforms
 
-- Linux x64
-- Linux arm64
-- MacOS x64
-- MacOS arm64
+Polykey is continuously built and tested on:
+
+- Linux x64 / arm64
+- MacOS x64 / arm64
 - Windows x64
 - Docker
 
@@ -29,28 +29,28 @@ Polykey is currently in beta. Its interface is at various levels of stability. S
 
 ## Getting Started
 
-To begin managing & sharing secrets effectively with Polykey, follow the tutorials in the sequence outlined below:
+Start your journey with Polykey by following the tutorials below in sequence:
 
 :::tip
-You may also reference the following [demo video](https://vimeo.com/884649667) for the getting started tutorial but you will first need to complete the installation instructions for Polykey-CLI.
+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)**: Set up Polykey CLI on your preferred platform.
-2. **[Bootstrap Keypair](/docs/tutorials/polykey-cli/bootstrapping)**: Initialize your node and connect to the Polykey network.
-3. **[Managing Vaults](/docs/tutorials/polykey-cli/managing-vaults)**: Create and manage secure vaults for effective secrets storage.
-4. **[Managing Secrets](/docs/tutorials/polykey-cli/managing-secrets)**: Explore comprehensive methods for handling and organizing secrets within vaults.
-5. **[Claiming Digital Identities](/docs/tutorials/polykey-cli/claiming-digital-identities)**: Authenticate and establish your identity across the Polykey network.
-6. **[Discovering Other User's Identities](/docs/tutorials/polykey-cli/discovering-other-users)**: Locate and verify identities of other users to manage access.
-7. **[Sharing Vaults](/docs/tutorials/polykey-cli/sharing-vaults)**: Share vaults securely with trusted peers.
-
-These initial tutorials will guide new users through the basic functionalities of setting up Polykey, starting their node (similar to creating a Web3 wallet connected to a P2P network), creating virtual encrypted vaults, and managing secret files within these vaults. This foundation prepares users for more advanced network functionalities, such as identity claims, discovery of other users' nodes, and secure sharing of secrets and vaults through end-to-end encryption.
+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.
 
-After mastering these basics, you'll be ready to explore intermediate use-cases such as:
+Explore advanced scenarios in subsequent sections, including:
 
 - Managing multiple local nodes
-- Linking multiple nodes to a single identity
-- Using Polykey's `env` command to inject secrets into your development environment
+- Integrating multiple nodes with a single identity
+- Injecting secrets directly into your development environments using Polykey’s `env` command
 
-These topics will be covered in more detail in the next section of our documentation, providing you with the tools to leverage Polykey's full potential in more complex operational environments.
+This will prepare you to fully exploit Polykey’s capabilities in diverse and complex operational settings.
 
 <DocCardList />

docs/tutorials/polykey-cli/claiming-digital-identities.md

@@ -1 +1,152 @@
-# Claiming Digital Identities
+# 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 <providerId>
+```
+
+`<providerId>`: 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.
+
+<img src="/images/cryptolink.png" alt="Cryptolink" style={{ width: '70%', height: 'auto' }} />
+
+### Command Usage
+
+_This image provides a demo example of the cryptographic link that is generated._
+
+:::info
+
+- `<providerIdentityId>`: The specific identity identifier from the provider you authenticated with, which you will claim.
+
+- `polykey identities claim` argument for `<providerIdentityID>` = `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.

docs/tutorials/polykey-cli/discovering-other-users.md

@@ -1,2 +1,166 @@
+# Discovering Users' Nodes and Managing Access Permissions
 
-# Discovering Other Users
+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 <gestaltId>
+```
+
+- `<gestaltId>`: 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 <gestaltId> <permissions>
+```
+
+- `<gestaltId>:` The Node ID or `Provider ID:Identity ID` of the node.
+- `<permissions>:` 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 <nodeId>
+```
+
+### 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 <gestaltId>
+polykey identities untrust <gestaltId>
+```
+
+## 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.