Add API key methods

.ci/doc/docker-compose.yml

@@ -22,7 +22,7 @@ services:
     image: redis:5
 
   elasticsearch:
-    image: kuzzleio/elasticsearch:7.4.0
+    image: kuzzleio/elasticsearch:7
     ulimits:
       nofile: 65536
 

.ci/docker-compose.yml

@@ -21,6 +21,6 @@ services:
     image: redis:5
 
   elasticsearch:
-    image: kuzzleio/elasticsearch:7.4.0
+    image: kuzzleio/elasticsearch:7
     ulimits:
       nofile: 65536

doc/7/controllers/auth/create-api-key/index.md

@@ -0,0 +1,70 @@
+---
+code: true
+type: page
+title: createApiKey
+description: Creates a new API key for the currently loggued user.
+---
+
+# createApiKey
+
+<SinceBadge version="7.1.0" />
+
+<SinceBadge version="Kuzzle 2.1.0" />
+
+Creates a new API key for the currently loggued user.
+
+<br />
+
+```js
+createApiKey(description, [options]);
+```
+
+<br />
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `description` | <pre>string</pre> | API key description |
+| `options` | <pre>object</pre> | Additional options |
+
+### options
+
+Additional query options
+
+| Property | Type<br />(default) | Description |
+| --- | --- | --- |
+| `expiresIn` | <pre>string/number</pre><br />(`-1`) | Expiration duration |
+| `_id` | <pre>string</pre><br />(`null`) | API key unique ID |
+| `refresh` | <pre>boolean</pre><br />(`false`) | If set to `wait_for`, Kuzzle will not respond until the API key is indexed |
+
+**Notes**:
+- `expiresIn`:
+  - if a raw number is provided (not enclosed between quotes), then the expiration delay is in milliseconds. Example: `86400000`
+  - if this value is a string, then its content is parsed by the [ms](https://www.npmjs.com/package/ms) library. Examples: `"6d"`, `"10h"`
+  - if `-1` is provided, the token will never expire
+
+## Resolves
+
+An object containing the newly created API key:
+
+| Name      | Type              | Description      |
+| --------- | ----------------- | ---------------- |
+| `_id`      | <pre>string</pre> | ID of the newly created API key |
+| `_source`  | <pre>object</pre> | API key content |
+
+The API key content has the following properties:
+
+| Name      | Type              | Description      |
+| --------- | ----------------- | ---------------- |
+| `userId`      | <pre>string</pre> | User kuid |
+| `expiresAt`  | <pre>number</pre> | Aexpiration date in UNIX micro-timestamp format (`-1` if the token never expires) |
+| `ttl`  | <pre>number</pre> | Original TTL |
+| `description`  | <pre>string</pre> | API key description |
+| `token`  | <pre>string</pre> | Authentication token associated with this API key |
+
+::: warning
+The authentication token `token` will never be returned by Kuzzle again. If you lose it, you'll have to delete the API key and recreate a new one.
+:::
+
+## Usage
+
+<<< ./snippets/create-api-key.js

doc/7/controllers/auth/create-api-key/snippets/create-api-key.js

@@ -0,0 +1,23 @@
+try {
+  await kuzzle.auth.login('local', { username: 'john.doe', password: 'password' });
+
+  const apiKey = await kuzzle.auth.createApiKey('Sigfox API key');
+
+  console.log(apiKey);
+  /*
+  {
+    _id: '-fQRa28BsidO6V_wmOcL',
+    _source: {
+      description: 'Sigfox API key',
+      userId: 'john.doe',
+      expiresAt: -1,
+      ttl: -1,
+      token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJqb2huLmRvZSIsImlhdCI6MTU3ODA0OTMxMn0.XO_keW6EtsCGmPzxVJCChU9VREakEECDGg-N5lhCfF8'
+    }
+  }
+  */
+
+  console.log('API key successfully created');
+} catch (e) {
+  console.error(e);
+}

doc/7/controllers/auth/create-api-key/snippets/create-api-key.test.yml

@@ -0,0 +1,22 @@
+name: auth#createApiKey
+description: Creates a new API key for the currently loggued user.
+hooks:
+  before: >
+    curl -H "Content-type: application/json" -d '{
+      "content": {
+        "profileIds": ["default"]
+      },
+      "credentials": {
+        "local": {
+          "username": "john.doe",
+          "password": "password"
+        }
+      }
+    }' "kuzzle:7512/users/john.doe/_create?refresh=wait_for"
+  after:
+    curl -XDELETE kuzzle:7512/users/john.doe
+template: default
+expected:
+  - "description: 'Sigfox API key'"
+  - "userId: 'john.doe'"
+  - API key successfully created

doc/7/controllers/auth/delete-api-key/index.md

@@ -0,0 +1,43 @@
+---
+code: true
+type: page
+title: deleteApiKey
+description: Deletes an API key for the currently loggued user.
+---
+
+# deleteApiKey
+
+<SinceBadge version="7.1.0" />
+
+<SinceBadge version="Kuzzle 2.1.0" />
+
+Deletes an API key for the currently loggued user.
+
+<br />
+
+```js
+deleteApiKey(id, [options]);
+```
+
+<br />
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | <pre>string</pre> | API key unique ID |
+| `options` | <pre>object</pre> | Additional options |
+
+### options
+
+Additional query options
+
+| Property | Type<br />(default) | Description |
+| --- | --- | --- |
+| `refresh` | <pre>boolean</pre><br />(`false`) | If set to `wait_for`, Kuzzle will not respond until the API key is indexed |
+
+## Resolves
+
+Resolves if the API key is successfully deleted.
+
+## Usage
+
+<<< ./snippets/delete-api-key.js

doc/7/controllers/auth/delete-api-key/snippets/delete-api-key.js

@@ -0,0 +1,9 @@
+try {
+  await kuzzle.auth.login('local', { username: 'john.doe', password: 'password' });
+
+  await kuzzle.auth.deleteApiKey('fQRa28BsidO6V_wmOcL');
+
+  console.log('API key successfully deleted');
+} catch (e) {
+  console.error(e);
+}

doc/7/controllers/auth/delete-api-key/snippets/delete-api-key.test.yml

@@ -0,0 +1,24 @@
+name: auth#deleteApiKey
+description: Deletes an API key for the currently loggued user
+hooks:
+  before: >
+    curl -H "Content-type: application/json" -d '{
+      "content": {
+        "profileIds": ["default"]
+      },
+      "credentials": {
+        "local": {
+          "username": "john.doe",
+          "password": "password"
+        }
+      }
+    }' "kuzzle:7512/users/john.doe/_create?refresh=wait_for"
+    &&
+    curl -XPOST -H "Content-type: application/json" -d '{
+      "description": "Sigfox API key"
+    }' "kuzzle:7512/users/john.doe/api-keys/_create?_id=fQRa28BsidO6V_wmOcL&refresh=wait_for"
+  after:
+    curl -XDELETE kuzzle:7512/users/john.doe
+template: default
+expected:
+  - API key successfully deleted

doc/7/controllers/auth/search-api-keys/index.md

@@ -0,0 +1,63 @@
+---
+code: true
+type: page
+title: searchApiKeys
+description: Searches API keys for the currently loggued user.
+---
+
+# searchApiKeys
+
+<SinceBadge version="7.1.0" />
+
+<SinceBadge version="Kuzzle 2.1.0" />
+
+Searches API keys for the currently loggued user.
+
+<br />
+
+```js
+searchApiKeys([query], [options]);
+```
+
+<br />
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `query` | <pre>object</pre> | Search query |
+| `options` | <pre>object</pre> | Additional options |
+
+### query
+
+The search query to apply to API keys content, using [ElasticSearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/query-dsl.html) syntax.
+
+If left empty, the result will return all available API keys of the currently loggued user.
+
+### options
+
+Additional query options
+
+| Property   | Type<br/>(default)   | Description  |
+| ---------- | ------------------ | ------------ |
+| `from`     | <pre>number</pre><br/>(`0`)     | Offset of the first document to fetch   |
+| `size`     | <pre>number</pre><br/>(`10`)    | Maximum number of documents to retrieve per page     |
+
+## Resolves
+
+Resolves an object with the following properties:
+
+| Name      | Type              | Description      |
+| --------- | ----------------- | ---------------- |
+| `hits`      | <pre>object[]</pre> | Array of objects representing found API keys |
+| `total`  | <pre>number</pre> | Total number of API keys found. Depending on pagination options, this can be greater than the actual number of API keys in a single result page |
+
+Each object of the `hits` array has the following properties:
+
+| Name      | Type              | Description      |
+| --------- | ----------------- | ---------------- |
+| `_id_`      | <pre>string</pre> | API key unique ID |
+| `_source`  | <pre>object</pre> | API key definition without the `token` field |
+
+
+## Usage
+
+<<< ./snippets/search-api-keys.js

doc/7/controllers/auth/search-api-keys/snippets/search-api-keys.js

@@ -0,0 +1,57 @@
+try {
+  const promises = [];
+
+  // Create some API keys for user "john.doe"
+  promises.push(
+    kuzzle.security.createApiKey('john.doe', 'Sigfox API key'));
+  promises.push(
+    kuzzle.security.createApiKey('john.doe', 'LoRa 6 month API key', {
+      expiresIn: '6m'
+    }));
+  promises.push(
+    kuzzle.security.createApiKey('john.doe', 'LoRa permanent API key', {
+      refresh: 'wait_for'
+    }));
+
+  await Promise.all(promises);
+
+  // Log as "john.doe"
+  await kuzzle.auth.login('local', { username: 'john.doe', password: 'password' });
+
+  const results = await kuzzle.auth.searchApiKeys({
+    match: {
+      description: 'LoRa'
+    }
+  });
+
+  console.log(results);
+  /*
+  {
+    "total": 2,
+    "hits": [
+      {
+        "_id": "znEwbG8BJASM_0-bWU-q",
+        "_source": {
+          "description": "LoRa permanent API key",
+          "userId": "john.doe",
+          "expiresAt": -1,
+          "ttl": -1
+        }
+      },
+      {
+        "_id": "zXEwbG8BJASM_0-bWU-q",
+        "_source": {
+          "description": "LoRa 1 year API key",
+          "userId": "john.doe",
+          "expiresAt": 31557600000,
+          "ttl": 360000
+        }
+      }
+    ]
+  }
+  */
+
+  console.log(`Found ${results.total} API keys matching "LoRa"`);
+} catch (e) {
+  console.error(e);
+}

doc/7/controllers/auth/search-api-keys/snippets/search-api-keys.test.yml

@@ -0,0 +1,20 @@
+name: auth#searchApiKeys
+description: Searches API keys for the currently loggued user.
+hooks:
+  before: >
+    curl -H "Content-type: application/json" -d '{
+      "content": {
+        "profileIds": ["default"]
+      },
+      "credentials": {
+        "local": {
+          "username": "john.doe",
+          "password": "password"
+        }
+      }
+    }' "kuzzle:7512/users/john.doe/_create?refresh=wait_for"
+  after:
+    curl -XDELETE kuzzle:7512/users/john.doe
+template: default
+expected:
+  - Found 2 API keys matching "LoRa"