Add [auth|security]:checkRights (#577)

Add [auth|security]:checkRights

Author: Yoann-Abbes

doc/7/controllers/auth/check-rights/index.md

@@ -0,0 +1,40 @@
+---
+code: true
+type: page
+title: checkRights
+description: Checks if an API action can be executed by the current user
+---
+
+# checkRights
+
+<SinceBadge version="Kuzzle 2.8.0"/>
+<SinceBadge version="auto-version"/>
+
+Checks if the provided API request can be executed by the current logged user.
+
+---
+
+```js
+checkRights(requestPayload)
+```
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `requestPayload` | <pre>object</pre> | Contains a [RequestPayload](/core/2/api/payloads/request) |
+
+## `requestPayload`
+
+The [RequestPayload](/core/2/api/payloads/request) must contains at least the following properties:
+
+- `controller`: API controller
+- `action`: API action
+
+---
+
+## Resolves
+
+A boolean telling whether the provided request would have been allowed or not.
+
+## Usage
+
+<<< ./snippets/check-rights.js

doc/7/controllers/auth/check-rights/snippets/check-rights.js

@@ -0,0 +1,19 @@
+const requestPayload = {
+  controller: 'document',
+  action: 'create',
+  index: 'nyc-open-data',
+  collection: 'yellow-taxi',
+  body: {
+    name: 'Melis'
+  }
+}
+
+try {
+  const result = await kuzzle.auth.checkRights(requestPayload);
+  console.log(result);
+  /*
+    true
+  */
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/auth/check-rights/snippets/check-rights.test.yml

@@ -0,0 +1,7 @@
+name: auth#checkRights
+description: Checks if an API action can be executed by the current user
+hooks:
+  before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}'
+  after: curl -X DELETE kuzzle:7512/users/foo
+template: default
+expected: true

doc/7/controllers/security/check-rights/index.md

@@ -0,0 +1,40 @@
+---
+code: true
+type: page
+title: checkRights
+description: Checks if an API action can be executed by a user
+---
+
+# checkRights
+
+<SinceBadge version="2.8.0"/>
+<SinceBadge version="auto-version"/>
+Checks if the provided API request can be executed by a user.
+
+---
+
+```js
+checkRights(kuid, requestPayload)
+```
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `kuid` | <pre>string</pre> | User [kuid](/core/2/guides/main-concepts/authentication#kuzzle-user-identifier-kuid) |
+| `requestPayload` | <pre>object</pre> | Contains a [RequestPayload](/core/2/api/payloads/request) |
+
+## `requestPayload`
+
+The [RequestPayload](/core/2/api/payloads/request) must contains at least the following properties:
+
+- `controller`: API controller
+- `action`: API action
+
+---
+
+## Resolves
+
+A boolean telling whether the provided request would have been allowed or not
+
+## Usage
+
+<<< ./snippets/check-rights.js

doc/7/controllers/security/check-rights/snippets/check-rights.js

@@ -0,0 +1,19 @@
+const requestPayload = {
+  controller: 'document',
+  action: 'create',
+  index: 'nyc-open-data',
+  collection: 'yellow-taxi',
+  body: {
+    name: 'Melis'
+  }
+}
+
+try {
+  const allowed = await kuzzle.security.checkRights('foo', requestPayload);
+  console.log(allowed);
+  /*
+    true
+  */
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/security/check-rights/snippets/check-rights.test.yml

@@ -0,0 +1,7 @@
+name: security#checkRights
+description: Checks if an API action can be executed by a user
+hooks:
+  before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}'
+  after: curl -X DELETE kuzzle:7512/users/foo
+template: default
+expected: true

src/controllers/Auth.ts

@@ -91,6 +91,24 @@ export class AuthController extends BaseController {
       .then(response => response.result);
   }
 
+  /**
+   * Checks if an API action can be executed by the current user
+   * 
+   * @see https://docs.kuzzle.io/sdk/js/7/controllers/auth/check-rights
+   * @param requestPayload Request to check
+   */
+  checkRights (
+    requestPayload: JSONObject
+  ): Promise<boolean> {
+
+    const request = {
+      body: requestPayload,
+      action: 'checkRights'
+    };
+    return this.query(request)
+      .then(response => response.result.allowed);
+  }
+
   /**
    * Deletes an API key for the currently loggued user.
    *

src/controllers/Security.js

@@ -39,6 +39,22 @@ class SecurityController extends BaseController {
       .then(response => response.result);
   }
 
+  /**
+   * Checks if an API action can be executed by the current user
+   * 
+   * @param {String} userId - User kuid
+   * @param {Object} requestPayload - Request to check
+   */
+  checkRights(kuid, requestPayload) {
+    const request = {
+      userId: kuid,
+      body: requestPayload,
+      action: 'checkRights'
+    };
+    return this.query(request)
+      .then(response => response.result.allowed);
+  }
+
   /**
    * Deletes an user API key.
    *