Updating documentation

signal-server-openapi.yaml

@@ -27,6 +27,9 @@ paths:
           description: default response
           content:
             '*/*': {}
+      security:
+      - authenticatedAccount: []
+      - {}
   /v1/accounts/number:
     put:
       tags:
@@ -56,12 +59,11 @@ paths:
     put:
       tags:
       - Account
+      summary: Confirm username hash
+      description: |
+        Authenticated endpoint. For a previously reserved username hash, confirm that this username hash is now taken
+        by this account.
       operationId: confirmUsernameHash
-      parameters:
-      - name: X-Signal-Agent
-        in: header
-        schema:
-          type: string
       requestBody:
         content:
           application/json:
@@ -69,12 +71,23 @@ paths:
               $ref: '#/components/schemas/ConfirmUsernameHashRequest'
         required: true
       responses:
-        default:
+        "200":
-          description: default response
+          description: Username hash confirmed successfully.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/UsernameHashResponse'
+        "401":
+          description: Account authentication check failed.
+        "409":
+          description: Given username hash doesn't match the reserved one or no reservation
+            found.
+        "410":
+          description: Username hash not available (username can't be used).
+        "422":
+          description: Invalid request format.
+        "429":
+          description: Ratelimited.
       security:
       - authenticatedAccount: []
   /v1/accounts/{transport}/code/{number}:
@@ -214,12 +227,66 @@ paths:
     delete:
       tags:
       - Account
+      summary: Delete username hash
+      description: |
+        Authenticated endpoint. Deletes previously stored username for the account.
       operationId: deleteUsernameHash
       responses:
-        default:
+        "204":
-          description: default response
+          description: Username successfully deleted.
+        "401":
+          description: Account authentication check failed.
+      security:
+      - authenticatedAccount: []
+  /v1/accounts/username_link:
+    put:
+      tags:
+      - Account
+      summary: Set username link
+      description: |
+        Authenticated endpoint. For the given encrypted username generates a username link handle.
+        Username link handle could be used to lookup the encrypted username.
+        An account can only have one username link at a time. Calling this endpoint will reset previously stored
+        encrypted username and deactivate previous link handle.
+      operationId: updateUsernameLink
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EncryptedUsername'
+        required: true
+      responses:
+        "200":
+          description: Username Link updated successfully.
           content:
-            application/json: {}
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UsernameLinkHandle'
+        "401":
+          description: Account authentication check failed.
+        "409":
+          description: Username is not set for the account.
+        "422":
+          description: Invalid request format.
+        "429":
+          description: Ratelimited.
+      security:
+      - authenticatedAccount: []
+    delete:
+      tags:
+      - Account
+      summary: Delete username link
+      description: |
+        Authenticated endpoint. Deletes username link for the given account: previously store encrypted username is deleted
+        and username link handle is deactivated.
+      operationId: deleteUsernameLink
+      responses:
+        "204":
+          description: Username Link successfully deleted.
+        "401":
+          description: Account authentication check failed.
+        "429":
+          description: Ratelimited.
       security:
       - authenticatedAccount: []
   /v1/accounts/{type}/preauth/{token}/{number}:
@@ -271,28 +338,62 @@ paths:
     get:
       tags:
       - Account
+      summary: Lookup username hash
+      description: |
+        Forced unauthenticated endpoint. For the given username hash, look up a user ID.
       operationId: lookupUsernameHash
       parameters:
-      - name: X-Signal-Agent
-        in: header
-        schema:
-          type: string
-      - name: X-Forwarded-For
-        in: header
-        schema:
-          type: string
       - name: usernameHash
         in: path
         required: true
         schema:
           type: string
       responses:
-        default:
+        "200":
-          description: default response
+          description: Account found for the given username.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AccountIdentifierResponse'
+        "400":
+          description: Request must not be authenticated.
+        "404":
+          description: Account not fount for the given username.
+      security:
+      - authenticatedAccount: []
+      - {}
+  /v1/accounts/username_link/{uuid}:
+    get:
+      tags:
+      - Account
+      summary: Lookup username link
+      description: |
+        Enforced unauthenticated endpoint. For the given username link handle, looks up the database for an associated encrypted username.
+        If found, encrypted username is returned, otherwise responds with 404 Not Found.
+      operationId: lookupUsernameLink
+      parameters:
+      - name: uuid
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+      responses:
+        "200":
+          description: Username link with the given handle was found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EncryptedUsername'
+        "404":
+          description: Username link was not found for the given handle.
+        "422":
+          description: Invalid request format.
+        "429":
+          description: Ratelimited.
+      security:
+      - authenticatedAccount: []
+      - {}
   /v1/accounts/registration_lock:
     put:
       tags:
@@ -326,12 +427,11 @@ paths:
     put:
       tags:
       - Account
+      summary: Reserve username hash
+      description: |
+        Authenticated endpoint. Takes in a list of hashes of potential username hashes, finds one that is not taken,
+        and reserves it for the current account.
       operationId: reserveUsernameHash
-      parameters:
-      - name: X-Signal-Agent
-        in: header
-        schema:
-          type: string
       requestBody:
         content:
           application/json:
@@ -339,12 +439,20 @@ paths:
               $ref: '#/components/schemas/ReserveUsernameHashRequest'
         required: true
       responses:
-        default:
+        "200":
-          description: default response
+          description: Username hash reserved successfully.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ReserveUsernameHashResponse'
+        "401":
+          description: Account authentication check failed.
+        "409":
+          description: All username hashes from the list are taken.
+        "422":
+          description: Invalid request format.
+        "429":
+          description: Ratelimited.
       security:
       - authenticatedAccount: []
   /v1/accounts/attributes:
@@ -2621,6 +2729,18 @@ components:
         uuid:
           type: string
           format: uuid
+    EncryptedUsername:
+      required:
+      - usernameLinkEncryptedValue
+      type: object
+      properties:
+        usernameLinkEncryptedValue:
+          maxItems: 128
+          minItems: 1
+          type: array
+          items:
+            type: string
+            format: byte
     ReserveUsernameHashResponse:
       type: object
       properties:
@@ -2750,6 +2870,14 @@ components:
           maxLength: 64
           minLength: 64
           type: string
+    UsernameLinkHandle:
+      required:
+      - usernameLinkHandle
+      type: object
+      properties:
+        usernameLinkHandle:
+          type: string
+          format: uuid
     BasicAuthorizationHeader:
       type: object
       properties:
@@ -3237,11 +3365,11 @@ components:
       properties:
         open:
           type: boolean
+        userAgent:
+          type: string
         createdTimestamp:
           type: integer
           format: int64
-        userAgent:
-          type: string
     WebSocketSessionContext:
       type: object
       properties: