feat(server): add a new PUT method to create a key with a specific identifier (#1473)

* feat(server): add optional `id` parameter to `createNewAccessKey` method

* Use `PUT` instead of `POST`.

* Make changes based on review.

* Update access key creation path to only allow ID on `PUT` calls.

* Expand test scenarios for key generation to `createAccessKey`.

* Add a `toHavePropertiesOf` custom Jasmine matcher.

* Add explicit test case for `ConflictError`.

* Revert "Add a `toHavePropertiesOf` custom Jasmine matcher."

This reverts commit 134e0df.

Author: sbruens

src/shadowbox/model/access_key.ts

@@ -49,6 +49,8 @@ export interface AccessKey {
 }
 
 export interface AccessKeyCreateParams {
+  // The unique identifier to give the access key. Throws if it exists.
+  readonly id?: AccessKeyId;
   // The encryption method to use for the access key.
   readonly encryptionMethod?: string;
   // The name to give the access key.
@@ -60,7 +62,7 @@ export interface AccessKeyCreateParams {
 }
 
 export interface AccessKeyRepository {
-  // Creates a new access key. Parameters are chosen automatically.
+  // Creates a new access key. Parameters are chosen automatically if not provided.
   createNewAccessKey(params?: AccessKeyCreateParams): Promise<AccessKey>;
   // Removes the access key given its id. Throws on failure.
   removeAccessKey(id: AccessKeyId);

src/shadowbox/model/errors.ts

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import {AccessKeyId} from './access_key';
+
 // TODO(fortuna): Reuse CustomError from server_manager.
 class OutlineError extends Error {
   constructor(message: string) {
@@ -35,7 +37,7 @@ export class PortUnavailable extends OutlineError {
 }
 
 export class AccessKeyNotFound extends OutlineError {
-  constructor(accessKeyId?: string) {
+  constructor(accessKeyId?: AccessKeyId) {
     super(`Access key "${accessKeyId}" not found`);
   }
 }
@@ -45,3 +47,9 @@ export class InvalidCipher extends OutlineError {
     super(`cipher "${cipher}" is not valid`);
   }
 }
+
+export class AccessKeyConflict extends OutlineError {
+  constructor(accessKeyId?: AccessKeyId) {
+    super(`Access key "${accessKeyId}" conflict`);
+  }
+}

src/shadowbox/server/api.yml

@@ -37,7 +37,7 @@ paths:
         - Server
       description: Changes the hostname for access keys.  Must be a valid hostname or IP address.  If it's a hostname, DNS must be set up independently of this API.
       requestBody:
-        required: true 
+        required: true
         content:
           application/json:
             schema:
@@ -51,7 +51,7 @@ paths:
               'IP address':
                 value: '{"hostname": "127.0.0.1"}'
       responses:
-        '204': 
+        '204':
           description: The hostname was successfully changed.
         '400':
           description: An invalid hostname or IP address was provided.
@@ -82,7 +82,7 @@ paths:
           description: The requested port wasn't an integer from 1 through 65535, or the request had no port parameter.
         '409':
           description: The requested port was already in use by another service.
-          
+
   /server/access-key-data-limit:
     put:
       description: Sets a data transfer limit for all access keys
@@ -157,7 +157,9 @@ paths:
                 dataLimit:
                   $ref: "#/components/schemas/DataLimit"
             examples:
-              '0':
+              'No params specified':
+                value: '{"method":"aes-192-gcm"}'
+              'Provide params':
                 value: '{"method":"aes-192-gcm","name":"First","password":"8iu8V8EeoFVpwQvQeS9wiD","limit":{"bytes":10000}}'
       responses:
         '201':
@@ -173,6 +175,43 @@ paths:
                 '1':
                   value: >-
                     {"id":"1","name":"Second","password":"xXxXxX","port":9795,"method":"chacha20-ietf-poly1305","accessUrl":"ss://ASDFHAKSDFSDAKFJ@0.0.0.0:9795/?outline=1"}
+    put:
+      description: Creates a new access key with a specific identifer
+      tags:
+        - Access Key
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                id:
+                  type: string
+                name:
+                  type: string
+                method:
+                  type: string
+                password:
+                  type: string
+                port:
+                  type: integer
+                dataLimit:
+                  $ref: "#/components/schemas/DataLimit"
+            examples:
+              '0':
+                value: '{"id":"123","method":"aes-192-gcm","name":"First","password":"8iu8V8EeoFVpwQvQeS9wiD","limit":{"bytes":10000}}'
+      responses:
+        '201':
+          description: The newly created access key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessKey"
+              examples:
+                '0':
+                  value: >-
+                    {"id":"my-identifier","name":"First","password":"XxXxXx","port":9795,"method":"chacha20-ietf-poly1305","accessUrl":"ss://SADFJSKADFJAKSD@0.0.0.0:9795/?outline=1"}
     get:
       description: Lists the access keys
       tags:
@@ -427,7 +466,7 @@ paths:
       responses:
         '204':
           description: Access key limit deleted successfully.
- 
+
 components:
   schemas:
     Server: