[#71] docs: Introduce APE overview

Signed-off-by: Airat Arifullin <aarifullin@yadro.com>

docs/ape.md

@@ -0,0 +1,85 @@
+# Access policy engine
+
+## General overview
+
+### Purpose
+
+Access policy engine (APE) is aimed at checking if a request can be performed over a resource by looking up the set chains of rules.
+
+#### Terms
+
+| Term           | Description                                                    | Structure overview     |
+| -------------- | -------------------------------------------------------------- | -------------- |
+| `Request`      | The action that is being performed on the `Resource`.                          | <ul><li>`Operation` - `GetObject`,`PutObject` etc.;</li><li>`Properties` - actor's public key, actor's attributes;</li><li>`Resource`.</li></ul> |
+| `Resource`     | The object that the request is being performed on. Check also [resource.md](./resource.md).   |  <ul><li>`Name` - strictly formatted string value;</li><li>`Properties`.</li></ul> |
+| `Chain`        | A chain of `Rule`-s defined for a specific target. Chains are strictly distinguished by `Name`-s , i.e. chains with name `ingress` are not intersected with chains with name `s3`. Chains are stored in serialized format.       | <ul><li>Base64-encoded `ID`;</li><li>List of `Rule`-s;</li><li>`MatchType` - defines rule status selection priority.</li></ul> |
+| `Rule`         | `Rule` defines which status is returned if `Request` matches all conditions.                                                         | <ul><li>`Status`: `Allow`, `AccessDenied`, `QuotaLimitReached`, `NoRuleFound`;</li><li>`Actions` - operation defined by a schema (`GetObject`, `PutContainer` etc.);</li><li>`Resources`;</li><li>`Any` - if `true` then `Reqeust` matches `Rule` if any `Condition` is `true`;</li><li>`Conditions`.</li></ul> |
+| `Name`   | `Name` of a chain (do not confuse with chain ID). `Name` defines a layer of `Chain`'s usage, so chains are distinguished by `Name`-s. Basically, `Name` refers to a protocol.                                                       | String value (`ingress`, `s3`, `iam`).      |
+| `Target`       | A scope of request. `Target` can be either simple (only namespace; only container; only user; only groups) or compound (namespace + container). | <ul><li>`Namespace`;</li><li>`Container`;</li><li>`User`;</li><li>`Groups`.</li></ul> |
+| `Engine`       | `Engine` checks a request in a scope defined by `Target`. First, it is trying to match a request with rules defined in `LocalOverrideStorage` and, then, in `MorphRuleChainStorage`.                                                          | <ul><li>`LocalOverrideStorage` - chains stored in the local override storage have the highest priority</li><li>`MorphRuleChainStorage` - basically, chains stored in `Policy` contract;</li><li>`ChainRouter` - looks up chains and try to match them with `Request`.</li></ul> |
+
+#### Details
+
+Here some entities are overviewed in more detail.
+
+##### Resource
+
+`Resource`'s name is strictly formatted, the format is defined by a schema (`native`, `aws` etc.). Examples:
+
+```bash
+# The resource is the particular object with the address within Root namespace
+native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr
+# The resource is all objects within the container within Root namespace
+native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/*
+# The resource is the particular container within the namespace
+native:container/namespace1/HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj
+# The resource is all containers within the namespace
+native:container/namespace1/*
+```
+
+##### Rule
+
+`Rule` works out if:
+
+ 1. a requests's operation matches the rule's `Actions`;
+ 2. resource name matches the rule's `Resources`;
+ 3. if all (or at least one if `Any=true`) conditions in `Condition` is met. Each condition defines how to retrieve
+and compare the retrieved value. If `Condition`'s `Object` is set to `Resource` then the value is retrieved from the
+resource's properties (example: container zone attribute). If `Object` is set to `Request`, the it's retrieved from the request's properties (example: actor's public key).
+
+###### Name matching
+
+`Resource`'s name in `Rule` may contain wildcard '*' that can be considered as a regular expression:
+
+```bash
+# The resource is all objects within the container within Root namespace
+native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/*
+```
+
+If an incoming request has such a resource name, then names are matched:
+
+```bash
+# The resource is all objects within the container within Root namespace
+native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr
+```
+
+If the incoming request has such a resource name that specifies a container's object within namespace, for instance, `namespicy`,
+then matching does not work out:
+
+```bash
+# The resource is all objects within the container within `namespicy` namespace:
+native:object/namespicy/HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr
+```
+
+##### Engine
+
+`Engine` is trying to match the request against **the target** looking up chain rules, firstly, in `LocalOverrideStorage` (these rules are also known as *local overrides*) and then in `MorphRuleChainStorage` (contract `Policy`). Both storages iterate chain rules according to the specified priority of the targets: `namespace` -> `container` -> `user` -> `groups`.
+
+#### Diagrams
+
+The diagram demonstrates a scenario in Storage node. The request `A` cannot be performed as APE matched
+the request and returned `Access Denied` status. The request `B` is allowed and the client gets `OK` status.  
+![Storage node](images/ape/storage_node_ape.svg)
+
+The diagram demonstrates a complex scenario with S3, IAM and Storage node.
+![S3 and IAM](images/ape/s3_ape.svg)

docs/images/ape/s3_ape.puml

@@ -0,0 +1,61 @@
+@startuml s3 ape
+
+participant "Client" as client
+
+participant "IAM" as iam
+participant "IAM -> APE converter" as converter
+
+box "S3" #HotPink
+  participant "S3 gateway" as s3
+end box
+
+box "Access Policy Engine (as s3 middleware)" #LightPink
+  participant "Local override storage" as s3localOverrides
+  participant "Chain router" as s3chainRouter
+end box
+
+box "Policy contract (shared)" 
+  participant "Morph rule storage" as morphRuleStorage
+end box
+
+box "Access Policy Engine (as storage middleware)" #LightGreen
+  participant "Chain Router" as storageChainRouter
+  participant "Local override storage" as storageLocalOverrides
+end box
+
+box "Storage node" #Green
+  participant "Object service" as obj
+  participant "Control service" as control
+end box
+
+group Request IAM to set a policy
+  client -> iam : Set IAM policy
+  iam -> converter : Convert IAM policy
+  converter -> iam : Return APE chain
+  iam -> morphRuleStorage : Store IAM policy and APE chain
+  iam -> s3localOverrides : Set S3 local overrides
+  iam -> client : OK
+end
+
+group Request S3 to set a policy
+  client -> s3 : Set bucket policy
+  s3 -> converter : Convert IAM policy
+  converter -> s3 : Return APE chain
+  s3 -> morphRuleStorage : Store bucket policy and APE chain
+  s3 -> client : OK
+end
+
+group Get object
+  client -> s3: GetObject
+  s3 -> s3chainRouter: Check if APE allows request for S3
+  note over s3chainRouter: matching the request with overrides and rules
+  s3chainRouter -> s3: Status: ALLOW
+  s3 -> obj: Get object
+  obj -> storageChainRouter: Check if APE allows the request
+  note over storageChainRouter : matching the request with overrides and rules
+  storageChainRouter -> obj: Status: ALLOW
+  obj -> s3: Response: OK, Object
+  s3 -> client: Response: OK, Object
+end
+
+@enduml

docs/images/ape/storage_node_ape.puml

@@ -0,0 +1,46 @@
+@startuml storage node ape
+!pragma teoz true
+
+participant "Administrator" as administrator
+participant "Client" as client
+
+box "Storage node" #Green
+  participant "Object service" as obj
+  participant "Control service" as control
+end box
+
+box "Access Policy Engine" #LightGreen
+  participant "Local override storage" as localOverrides
+  participant "Chain Router" as chainRouter
+  participant "Morph rule storage" as morphRuleStorage
+end box
+
+group Set local override
+  client -> control: Add local override
+  control -> localOverrides: Save override in DB
+  localOverrides -> control: OK
+  control -> client: OK
+end
+
+group Update state in Policy contract
+  administrator -> morphRuleStorage: Add chain
+  morphRuleStorage -> administrator: OK
+end
+
+group Perform a request A
+  client -> obj : Sending a request
+  obj -> chainRouter: Check if APE allows the request
+  note over chainRouter : Fetches local overrides and rules defined for a target/targets and looks for a match
+  chainRouter -> obj: APE returns status: "ACCESS DENIED"
+  obj -> client: Response: "the request is denied"
+end
+
+group Perform a request B
+  client -> obj : Sending a request
+  obj -> chainRouter: Check if APE allows the request
+  note over chainRouter : Fetches local overrides and rules defined for a target/targets and looks for a match
+  chainRouter -> obj: APE returns status: "ALLOW"
+  obj -> client: Response: "OK"
+end
+
+@enduml