diff --git a/signal-server-openapi.yaml b/signal-server-openapi.yaml index 066dd558e..89b23946b 100644 --- a/signal-server-openapi.yaml +++ b/signal-server-openapi.yaml @@ -1566,6 +1566,80 @@ paths: description: "If present, an positive integer indicating the number\ \ of seconds before a subsequent attempt could succeed" style: simple + /v1/devices/restore_account/{token}: + get: + tags: + - Devices + summary: Wait for 'restore account' request + operationId: waitForDeviceTransferRequest + parameters: + - name: token + in: path + required: true + schema: + maximum: 64 + maxLength: 64 + minLength: 0 + type: string + description: A randomly-generated token identifying the request for device-to-device + transfer. + - name: timeout + in: query + schema: + maximum: 3600 + minimum: 1 + type: integer + description: |2 + The amount of time (in seconds) to wait for a response. If a transfer archive for the authenticated + device is not available within the given amount of time, this endpoint will return a status of HTTP/204. + format: int32 + default: 30 + responses: + "200": + description: A 'restore account' request was received for the given token + content: + application/json: + schema: + $ref: '#/components/schemas/RestoreAccountRequest' + "204": + description: No 'restore account' request for the given token was received + before the call completed; clients may repeat the call to continue waiting + "400": + description: The given token or timeout was invalid + "429": + description: Rate-limited; try again after the prescribed delay + put: + tags: + - Devices + summary: Signals that a new device is requesting restoration of account data + by some method + description: | + Signals that a new device is requesting restoration of account data by some method. Devices waiting via the + "wait for 'restore account' request" endpoint will be notified that the request has been issued. + operationId: recordRestoreAccountRequest + parameters: + - name: token + in: path + required: true + schema: + maximum: 64 + maxLength: 64 + minLength: 0 + type: string + description: A randomly-generated token identifying the request for device-to-device + transfer. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RestoreAccountRequest' + responses: + "204": + description: Success + "422": + description: The request object could not be parsed or was otherwise invalid + "429": + description: Rate-limited; try again after the prescribed delay /v1/devices/transfer_archive: get: tags: @@ -1810,6 +1884,39 @@ paths: description: default response content: '*/*': {} + /v1/key-transparency/distinguished: + get: + tags: + - KeyTransparency + summary: Get the current value of the distinguished key + description: | + Enforced unauthenticated endpoint. The response contains the distinguished tree head to prove consistency + against for future calls to `/search` and `/distinguished`. + operationId: getDistinguishedKey + parameters: + - name: lastTreeHeadSize + in: query + description: The distinguished tree head size returned by a previously verified + call + schema: + type: integer + format: int64 + responses: + "200": + description: The `distinguished` search key exists in the log + content: + application/json: + schema: + $ref: '#/components/schemas/KeyTransparencyDistinguishedKeyResponse' + "400": + description: Invalid request. See response for any available details. + "422": + description: Invalid request format + "429": + description: Rate-limited + security: + - authenticatedAccount: [] + - {} /v1/key-transparency/monitor: post: tags: @@ -1832,10 +1939,12 @@ paths: application/json: schema: $ref: '#/components/schemas/KeyTransparencyMonitorResponse' + "400": + description: Invalid request. See response for any available details. "404": description: At least one search key lookup did not find the key "429": - description: Ratelimited + description: Rate-limited "422": description: Invalid request format security: @@ -1862,12 +1971,14 @@ paths: application/json: schema: $ref: '#/components/schemas/KeyTransparencySearchResponse' + "400": + description: Invalid request. See response for any available details. "403": description: At least one search key lookup to value mapping was invalid "404": description: At least one search key lookup did not find the key "429": - description: Ratelimited + description: Rate-limited "422": description: Invalid request format security: @@ -4477,6 +4588,22 @@ components: $ref: '#/components/schemas/ApnRegistrationId' gcmToken: $ref: '#/components/schemas/GcmRegistrationId' + RestoreAccountRequest: + required: + - method + type: object + properties: + method: + type: string + description: The method by which the new device has requested account data + restoration + enum: + - REMOTE_BACKUP + - LOCAL_BACKUP + - DEVICE_TRANSFER + - DECLINE + description: | + Represents a request from a new device to restore account data by some method. TransferArchiveUploadedRequest: type: object properties: @@ -4521,6 +4648,16 @@ components: type: object client: $ref: '#/components/schemas/WebSocketClient' + KeyTransparencyDistinguishedKeyResponse: + required: + - distinguishedKeyResponse + type: object + properties: + distinguishedKeyResponse: + type: string + description: The response for the distinguished tree head encoded in standard + un-padded base64 + format: byte KeyTransparencyMonitorResponse: required: - monitorResponse