docs: shield docs 0.5.0 (#186)

* docs: add intro, glossary, server-setup-wip

* docs: concepts and tour

* docs: add api and cli ref

* docs: add guide

* docs: change heading

* docs: separate proxy and auth architecture

* docs: sentence correction

* docs: fix new schema changes

docs/docs/concepts/architecture.md

@@ -1,10 +1,7 @@
 # Architecture
-
 Shield exposes both HTTP and gRPC APIs to manage data. It also proxy APIs to other services. Shield talks to SpiceDB instance to check for authorization.
 
-![Shield Architecture](../../static/img/architecture.svg)
-
-## Technologies
+## Tools and Technologies
 
 Shield is developed with
 
@@ -27,4 +24,92 @@ Another DB instance is for SpiceDB to store all the data needed for authorizatio
 
 ### SpiceDB
 
-Shield push all the policies and relationships data to SpiceDB. All this data is needed to make the authorization decision. Shield connects to SpiceDB instance via gRPC
+Shield push all the policies and relationships data to SpiceDB. All this data is needed to make the authorization decision. Shield connects to SpiceDB instance via gRPC.
+
+## Overall System Architecture - Shield as an Authorization Service
+
+Shield can be used as an authorization service using the `check` API. Currently, we just allow to check permisison over a single resource, i.e. 
+`can a USER do an ACTION on this RESOURCE`.
+
+![Overall System Architecture Authorization](./shield-authorization-architecture.png)
+
+The API gives a boolean response. You can refer this [guide](docs/guides/check-permission.md) for usage information.
+
+## Overall System Architecture - Shield as a Proxy
+
+![Overall System Architecture Proxy](./overall-proxy-architecture.png)
+
+The above diagram shows the system architecture which uses shield as a proxy. 
+
+Let's have a look at the major events:
+
+- Middleware: Middlewares as their names suggest are engaged befor the request is proxied.
+There are a few different middlewares which are `rule-matching`, `prefix`, `basic_auth`, `attribute` and `authz`.
+We'll discuss each one in details in the upcoming sections.
+
+- Hook: Hooks are engaged after a response is received form the backend service. Currently we just have a single resource creation hook named `authz`. 
+
+Let's have a look at the Shield's Architecture where we will also be discussing about the different middlewares and hoooks.
+
+## Shield Proxy Architecture
+
+![Shield Proxy Architecture](./shield-proxy-architecture.png)
+
+Sheild's proxy is build from two major components which are middlewares and hooks. Let's dive deeper into each of these components.
+
+### Middleware
+
+Middlewares in shield have the following interface. 
+
+```go
+type Middleware interface {
+	Info() *MiddlewareInfo
+	ServeHTTP(rw http.ResponseWriter, req *http.Request)
+}
+
+type MiddlewareInfo struct {
+	Name        string
+	Description string
+}
+```
+
+Shield is designed to execute the middlewares in a fixed order maintained by a stack.
+The order followed is
+- Rule match
+- Attributes
+- Basic auth
+- Authz
+- Prefix
+
+#### Rule match
+The rule match middleware finds the rule configured for a path and enriches the `ctx` with it. It also enriched the `ctx` with the request body.
+
+#### Attributes
+The attributes middleware builds a map of the attributes passed and enriches the `ctx` with it.
+
+#### Basic auth
+This middleware can be configured to support basic authentication with shield.
+
+#### Authz
+This middleware checks in the SpiceDB if the user is authorized with atleast one (OR operation) the permissions.
+
+#### Prefix
+This middleware strips a configured prefix from the request's URL path.
+
+## Hook
+Hooks in shield have the following interface.
+
+```go
+type Service interface {
+	Info() Info
+	ServeHook(res *http.Response, err error) (*http.Response, error)
+}
+```
+
+Shield only have a single hook
+
+- Authz
+
+#### Authz
+Authz hook persists the resource been created in the configfured backencd in Shield's DB. It does not create any relation by default but relations can be configured too. The relashions are created and stored both in Shield's DB and SpiceDB.
+

docs/docs/concepts/glossary.md

@@ -1,40 +1,57 @@
 # Glossary
 
-## User
+## Backend
 
-A User represents a profile of a user. User has to create a profile with their name, email, and metadata.
+External Service which wants to use Shield for authz. It can verify access via Shield Proxy & API.
 
-## Group
+## Permission
 
-A Group represents a group of [users](#user). There are predefined [roles](#role) for a user like Team Admin and Team Members. By default, every user gets a Team member role. Team admin can add and remove members from the Group.
+Ability to carry out any action, in Shield or configured Backends.
 
-## Role
+## Principal
 
-Within a [namespace](#namespace), a role will get assigned to [users](#user). A role is needed to define [policy](#policy). There are predefined roles in a namespace. Users can also create custom roles.
+To whom we can grant Permission to. They can be of types:
 
-## Namespace
+1. User: A person or service account who can be a Principal. It is identified by Email ID.
+2. Group: Collection of Users.
+3. All Registered Users: Collection of users who have registered in Shield. Any user who registers in Shield becomes part of this Principal.
 
-Namespace provides scope for the [policies](#policy). There are predefined namespaces like [organization](#orgnaization), [project](#project), [group](#group), etc. Users can also create custom namespaces.
 
-## Policy
+## Resource
 
-A Policy defines what [actions](#action) a [role](#role) can perform in a [namespace](#namespace). All policies in a namespace will be used to generate schema for [spicedb](#spicedb).
+Entity which needs authorization to be accessed. For example, a GCE instance is a resource over which we need permission such as edit & view.
 
-## Action
+## Resource Type
 
-Within a [namespace](#namespace), a role can perform certain actions. A action is needed to define [policy](#policy).
+Classification that contains Resource instances. For example, GCE can be a resource type for GCE instances.
 
 ## Project
 
-A Project is a scope in which a User can create and manage Resources.
+By which we can group Resources, of various different Resource Types, who have common environment.
 
-## Orgnaization
+## Organization
 
-An Orgnaization is just a group of Projects. [Groups](#group) also belongs to Orgnaization.
+Organization is the root node in the hierarchy of Resources, being a collection of Projects.
 
-## Resource
+## Namespace
+
+Type of objects over which we want authorization. They are of two types:
+
+1. System Namespace: Objects like Organization, Project & Team, over which we need authorization to actions such as adding user to team, adding user as owner of project.
+
+2. Resource Namespace: Resources Types over which we need authorization. For example, we need edit & view permissions over GCE Instances.
+
+## Role
+
+Its an IAM Identity that describes what are the permissions one Principal has.
+
+## Policy
+
+Defines what Permission does a Role have.
+
+## Entity
 
-Resources are just custom namespaces in which user can define policies. All Resources also gets default policies.
+Instance of a namespace.
 
 ## Spicedb
 

docs/docs/guides/adding-metadata-key.md

@@ -0,0 +1,34 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+# Adding Metadata Keys
+
+A metadata-key in Shield looks like
+
+```json
+{
+    "metadatakey": {
+        "key": "manager",
+        "description": "manager of this user"
+    }
+}
+```
+
+## API Interface
+
+### Create metadata keys
+
+<Tabs groupId="api">
+  <TabItem value="HTTP" label="HTTP" default>
+        <CodeBlock className="language-bash">
+    {`$ curl --location --request POST 'http://localhost:8000/admin/v1beta1/metadatakey'
+--header 'Content-Type: application/json'
+--header 'Accept: application/json'
+--data-raw '{
+  "key": "manager",
+  "description": "manager of this user"
+}'`}
+    </CodeBlock>
+  </TabItem>
+</Tabs>

docs/docs/guides/check-permission.md

@@ -1,22 +1,27 @@
-# Check Permission
-
-There are two ways to check permission in the shield,
-
-1. REST/gRPC API
-2. Proxy Middleware
-
-## REST/gRPC API
-
-```sh
-POST v1beta1/check/{resourceId} HTTP/1.1
-Host: localhost:8000
-Content-Type: application/json
-
-{
-  "actionId": "read",
-  "namespaceId": "test-namespace"
-}
-```
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+# Checking Pemrissions
+
+There are two ways to check a user permission on a resource in shield,
+## API Interface
+
+<Tabs groupId="api">
+  <TabItem value="HTTP" label="HTTP" default>
+        <CodeBlock className="language-bash">
+    {`$ curl --location --request POST 'http://localhost:8000/admin/v1beta1/check'
+--header 'Content-Type: application/json'
+--header 'Accept: application/json'
+--header 'X-Shield-Email: doe.john@odpf.io'
+--data-raw '{
+  "objectId": "test-resource-beta1",
+  "objectNamespace": "entropy/firehose",
+  "permission": "owner"
+}'`}
+    </CodeBlock>
+  </TabItem>
+</Tabs>
 
 ## Proxy Middleware
 
@@ -44,4 +49,4 @@ The shield will read the action from the config, resource id from the path param
                 key: X-Shield-Project
                 type: header
                 source: request
-```
+```