diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5e3de2b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,78 @@ +--- +slug: / +displayed_sidebar: docs +--- + +# Polykey Documentation + +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](./how-to-guides/) - these are short guides on how to achieve a specific use-case which makes assumptions on the reader +* [Theory](./reference/) - 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 + +Check out [Getting Started](./tutorials/getting-started.md) to deploy your first Polykey node. + + + +## 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 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 infrastructure key management. +* Decentralized and local-first software that does not hand over your secrets to the cloud. You maintain sovereignty over your secrets on your devices. +* Easily backup and synchronise your secrets across all your devices: desktop, mobile or server. +* End to end encryption for all network communication. +* All data is encrypted at rest, thus preventing compromise even if devices are lost or stolen. + +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: + +* Secrets Management +* Decentralized Trust + +### Secrets Management + +Polykey was built from the ground up to focus on secrets management. + +Secrets can be any kind of data that enables some sort of capability in the physical or virtual world. + +The world is full of secrets. For example, a password is a secret that enables you to login to a website. A private key is a secret that enables you to sign and verify some data. A symmetric key is a secret that enables you to encrypt and decrypt some data. A token is a secret that enables software agents and machines to authenticate to remote services. A credit card is a secret that enables payments. + +Polykey is designed to manage all kinds of secrets. It is not limited to 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 filesystem with automatic version history. Vaults can be shared with other Polykey agents. + +Polykey's secrets management concept provides users with secure commuication and secure computation. + +### Decentralized Trust + +Sharing secrets depends secure communications. Secure communications depends on trusted identities. + +Polykey introduced a concept called "Gestalt Identity". + +A Gestalt Identity is a collection of digital identities (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 Polykey node as its only identity. Link up your digital identities to the node in order to expand your gestalt. + +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 + +TBD diff --git a/docs/development-guide/README.md b/docs/development-guide/README.md new file mode 100644 index 0000000..f395b2f --- /dev/null +++ b/docs/development-guide/README.md @@ -0,0 +1,5 @@ +import DocCardList from '@theme/DocCardList'; + +# Development Guide + + diff --git a/docs/home.md b/docs/home.md deleted file mode 100644 index 0ceb77c..0000000 --- a/docs/home.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -slug: / -displayed_sidebar: docs ---- - -# Home - -Polykey - a decentralized secrets management system! - -Visit our [Getting Started](https://github.com/MatrixAI/Polykey/wiki/getting-started) Guide to deploy your very own PolyKey agent. - -Alternatively, review our **Reference** or **Background Information** sections. - -# About - -PolyKey is a decentralised distributed peer to peer (P2P) secret sharing & secret -management system. It is intended to be used by both humans and machines. -It synthesise a unified workflow between interactive password management and -infrastructure key management. - -This project PolyKey (library) is the core library for running PolyKey. It -provides a CLI `polykey` or `pk` for interacting with the PolyKey system. The -main desktop GUI is located at https://github.com/MatrixAI/PolyKey. - -PolyKey involves running distributed keynodes, which we will refer to as "nodes". -A host system can run multiple nodes. Each node manages one or more vaults which -are encrypted filesystems with automatic version history. You can share these -vaults with other users of PolyKey who are running their own keynodes. - -# Wiki - -The wiki is structured using Divio system: https://documentation.divio.com/ - - - -* Tutorials - these are a series of steps to introduce Polykey to new beginners to achieve a practical outcome -* How-To Guides - these are short guides on how to achieve a specific use-case which makes assumptions on the reader -* Reference - these are useful when you need remember how to use a particular command or function -* Theory - these are important for understanding the "why" of Polykey - -Each sub-project has their own `Reference` and `How-To Guides`, however most `Tutorials`, `How-To Guides` and `Theory` are all located here in the master-project. diff --git a/docs/how-to-guides/README.md b/docs/how-to-guides/README.md new file mode 100644 index 0000000..45af6fd --- /dev/null +++ b/docs/how-to-guides/README.md @@ -0,0 +1,5 @@ +import DocCardList from '@theme/DocCardList'; + +# How-To Guides + + diff --git a/docs/reference/README.md b/docs/reference/README.md new file mode 100644 index 0000000..d6ae8b7 --- /dev/null +++ b/docs/reference/README.md @@ -0,0 +1,5 @@ +import DocCardList from '@theme/DocCardList'; + +# Reference + + diff --git a/docs/theory/README.md b/docs/theory/README.md new file mode 100644 index 0000000..161f49f --- /dev/null +++ b/docs/theory/README.md @@ -0,0 +1,5 @@ +import DocCardList from '@theme/DocCardList'; + +# Theory + + diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 0000000..ed1426f --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,5 @@ +import DocCardList from '@theme/DocCardList'; + +# Tutorials + + diff --git a/docs/tutorials/installation.md b/docs/tutorials/installation.md new file mode 100644 index 0000000..a6c9197 --- /dev/null +++ b/docs/tutorials/installation.md @@ -0,0 +1,15 @@ +# Installation + +Polykey is a set of open source packages: + +* [Polykey Core Library](https://github.com/MatrixAI/Polykey) +* [Polykey CLI](https://github.com/MatrixAI/Polykey-CLI) +* [Polykey Desktop](https://github.com/MatrixAI/Polykey-Desktop) +* [Polykey Mobile](https://github.com/MatrixAI/Polykey-Mobile) + +## Polykey Core Library + +The Polykey core library + + +### Requirements diff --git a/docusaurus.config.js b/docusaurus.config.js index 1fda3ca..3fe1409 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -83,9 +83,9 @@ const config = { items: [ { type: 'doc', - docId: 'home', + docId: 'README', position: 'left', - label: 'Home', + label: 'Docs', }, { href: 'https://github.com/MatrixAI/Polykey-Docs', diff --git a/sidebars.js b/sidebars.js index 094fcf8..de8d280 100644 --- a/sidebars.js +++ b/sidebars.js @@ -7,14 +7,23 @@ const sidebars = { type: 'category', label: 'Tutorials', collapsed: false, + link: { + type: 'doc', + id: 'tutorials/README', + }, items: [ - 'tutorials/getting-started' + 'tutorials/installation', + 'tutorials/getting-started', ] }, { type: 'category', label: 'How To Guides', collapsed: false, + link: { + type: 'doc', + id: 'how-to-guides/README', + }, items: [ { type: 'category', @@ -55,6 +64,10 @@ const sidebars = { type: 'category', label: 'Theory', collapsed: false, + link: { + type: 'doc', + id: 'theory/README', + }, items: [ 'theory/secrets-management', 'theory/decentralized-trust-network', @@ -66,6 +79,10 @@ const sidebars = { type: 'category', label: 'Reference', collapsed: false, + link: { + type: 'doc', + id: 'reference/README', + }, items: [ { type: 'category', @@ -192,6 +209,10 @@ const sidebars = { type: 'category', label: 'Development Guide', collapsed: false, + link: { + type: 'doc', + id: 'development-guide/README', + }, items: [ 'development-guide/roadmap', 'development-guide/software-architecture',