PR(DOCS): Update documentation & run make docs

shahzadlone · Oct 3, 2024 · 8f52a19 · 8f52a19
1 parent 6fb7b84
commit 8f52a19
Show file tree

Hide file tree

Showing 5 changed files with 168 additions and 1 deletion.
diff --git a/acp/README.md b/acp/README.md
@@ -631,6 +631,70 @@ Result:
 Error: document not found or not authorized to access
 ```
 
+### Revoking Access To Private Documents
+
+To revoke access to a document for an actor, we must delete the relationship between the
+actor and the document. Inorder to delete the relationship we require all of the following:
+
+1) Target DocID: The docID of the document we want to delete a relationship for.
+2) Collection Name: The name of the collection that has the Target DocID.
+3) Relation Name: The type of relation (name must be defined within the linked policy on collection).
+4) Target Identity: The identity of the actor the relationship is being deleted for.
+5) Requesting Identity: The identity of the actor that is making the request.
+
+Notes:
+  - ACP must be available (i.e. ACP can not be disabled).
+  - The target document must be registered with ACP already (policy & resource specified).
+  - The requesting identity MUST either be the owner OR the manager (manages the relation) of the resource.
+  - If the relationship record was not found, then it will be a no-op.
+
+Consider the same policy and added relationship from the previous example in the section above where we learnt
+how to share the document with other actors. 
+
+We made the document accessible to an actor by adding a relationship:
+```sh
+defradb client acp relationship add \
+--collection Users \
+--docID bae-ff3ceb1c-b5c0-5e86-a024-dd1b16a4261c \
+--relation reader \
+--actor did:key:z7r8os2G88XXBNBTLj3kFR5rzUJ4VAesbX7PgsA68ak9B5RYcXF5EZEmjRzzinZndPSSwujXb4XKHG6vmKEFG6ZfsfcQn \
+--identity e3b722906ee4e56368f581cd8b18ab0f48af1ea53e635e3f7b8acd076676f6ac
+```
+
+Result:
+```json
+{
+  "ExistedAlready": false
+}
+```
+
+Similarly, inorder to revoke access to a document we have the following command to delete the relationship:
+```sh
+defradb client acp relationship delete \
+--collection Users \
+--docID bae-ff3ceb1c-b5c0-5e86-a024-dd1b16a4261c \
+--relation reader \
+--actor did:key:z7r8os2G88XXBNBTLj3kFR5rzUJ4VAesbX7PgsA68ak9B5RYcXF5EZEmjRzzinZndPSSwujXb4XKHG6vmKEFG6ZfsfcQn \
+--identity e3b722906ee4e56368f581cd8b18ab0f48af1ea53e635e3f7b8acd076676f6ac
+```
+
+Result:
+```json
+{
+  "RecordFound": true
+}
+```
+
+**Note: If the same relationship is deleted again (or a record for a relationship does not exist) then the `RecordFound`
+would be false, indicating no-op**
+
+Now the other actor can no longer read:
+```sh
+defradb client collection docIDs --identity 4d092126012ebaf56161716018a71630d99443d9d5217e9d8502bb5c5456f2c5
+```
+
+**Result is empty from the above command**
+
 ## DAC Usage HTTP:
 
 ### Authentication

diff --git a/cli/acp_relationship_delete.go b/cli/acp_relationship_delete.go
@@ -40,8 +40,9 @@ func MakeACPRelationshipDeleteCommand() *cobra.Command {
 		Short: "Delete relationship",
 		Long: `Delete relationship
 
-To revoke access to a document (or delete a relationship), we must delete a relationship link between the
+To revoke access to a document for an actor, we must delete the relationship between the
 actor and the document. Inorder to delete the relationship we require all of the following:
+
 1) Target DocID: The docID of the document we want to delete a relationship for.
 2) Collection Name: The name of the collection that has the Target DocID.
 3) Relation Name: The type of relation (name must be defined within the linked policy on collection).

diff --git a/docs/website/references/cli/defradb_client_acp_relationship.md b/docs/website/references/cli/defradb_client_acp_relationship.md
@@ -38,4 +38,5 @@ Interact with the acp relationship features of DefraDB instance
 
 * [defradb client acp](defradb_client_acp.md)	 - Interact with the access control system of a DefraDB node
 * [defradb client acp relationship add](defradb_client_acp_relationship_add.md)	 - Add new relationship
+* [defradb client acp relationship delete](defradb_client_acp_relationship_delete.md)	 - Delete relationship
 
diff --git a/docs/website/references/cli/defradb_client_acp_relationship_delete.md b/docs/website/references/cli/defradb_client_acp_relationship_delete.md
@@ -0,0 +1,73 @@
+## defradb client acp relationship delete
+
+Delete relationship
+
+### Synopsis
+
+Delete relationship
+
+To revoke access to a document for an actor, we must delete the relationship between the
+actor and the document. Inorder to delete the relationship we require all of the following:
+
+1) Target DocID: The docID of the document we want to delete a relationship for.
+2) Collection Name: The name of the collection that has the Target DocID.
+3) Relation Name: The type of relation (name must be defined within the linked policy on collection).
+4) Target Identity: The identity of the actor the relationship is being deleted for.
+5) Requesting Identity: The identity of the actor that is making the request.
+
+Notes:
+  - ACP must be available (i.e. ACP can not be disabled).
+  - The target document must be registered with ACP already (policy & resource specified).
+  - The requesting identity MUST either be the owner OR the manager (manages the relation) of the resource.
+  - If the relationship record was not found, then it will be a no-op.
+  - Learn more about [ACP & DPI Rules](/acp/README.md)
+
+Example: Let another actor (4d092126012ebaf56161716018a71630d99443d9d5217e9d8502bb5c5456f2c5) read a private document:
+  defradb client acp relationship delete \
+	--collection Users \
+	--docID bae-ff3ceb1c-b5c0-5e86-a024-dd1b16a4261c \
+	--relation reader \
+	--actor did:key:z7r8os2G88XXBNBTLj3kFR5rzUJ4VAesbX7PgsA68ak9B5RYcXF5EZEmjRzzinZndPSSwujXb4XKHG6vmKEFG6ZfsfcQn \
+	--identity e3b722906ee4e56368f581cd8b18ab0f48af1ea53e635e3f7b8acd076676f6ac
+
+
+```
+defradb client acp relationship delete [--docID] [-c --collection] [-r --relation] [-a --actor] [-i --identity] [flags]
+```
+
+### Options
+
+```
+  -a, --actor string        Actor to delete relationship for
+  -c, --collection string   Collection that has the resource and policy for object
+      --docID string        Document Identifier (ObjectID) to delete relationship for
+  -h, --help                help for delete
+  -r, --relation string     Relation that needs to be deleted within the relationship
+```
+
+### Options inherited from parent commands
+
+```
+  -i, --identity string             Hex formatted private key used to authenticate with ACP
+      --keyring-backend string      Keyring backend to use. Options are file or system (default "file")
+      --keyring-namespace string    Service name to use when using the system backend (default "defradb")
+      --keyring-path string         Path to store encrypted keys when using the file backend (default "keys")
+      --log-format string           Log format to use. Options are text or json (default "text")
+      --log-level string            Log level to use. Options are debug, info, error, fatal (default "info")
+      --log-output string           Log output path. Options are stderr or stdout. (default "stderr")
+      --log-overrides string        Logger config overrides. Format <name>,<key>=<val>,...;<name>,...
+      --log-source                  Include source location in logs
+      --log-stacktrace              Include stacktrace in error and fatal logs
+      --no-keyring                  Disable the keyring and generate ephemeral keys
+      --no-log-color                Disable colored log output
+      --rootdir string              Directory for persistent data (default: $HOME/.defradb)
+      --secret-file string          Path to the file containing secrets (default ".env")
+      --source-hub-address string   The SourceHub address authorized by the client to make SourceHub transactions on behalf of the actor
+      --tx uint                     Transaction ID
+      --url string                  URL of HTTP endpoint to listen on or connect to (default "127.0.0.1:9181")
+```
+
+### SEE ALSO
+
+* [defradb client acp relationship](defradb_client_acp_relationship.md)	 - Interact with the acp relationship features of DefraDB instance
+
diff --git a/docs/website/references/http/openapi.json b/docs/website/references/http/openapi.json
@@ -589,6 +589,34 @@
             }
         },
         "/acp/relationship": {
+            "delete": {
+                "description": "Delete an actor relationship using acp system",
+                "operationId": "delete relationship",
+                "requestBody": {
+                    "content": {
+                        "text/plain": {
+                            "schema": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "required": true
+                },
+                "responses": {
+                    "200": {
+                        "$ref": "#/components/responses/success"
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/error"
+                    },
+                    "default": {
+                        "description": ""
+                    }
+                },
+                "tags": [
+                    "acp_relationship"
+                ]
+            },
             "post": {
                 "description": "Add an actor relationship using acp system",
                 "operationId": "add relationship",