# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
  title: Matrix Identity Service Lookup API
  version: 2.0.0
paths:
  /hash_details:
    get:
      summary: Gets hash function information from the server.
      description: |-
        Gets parameters for hashing identifiers from the server. This can include
        any of the algorithms defined in this specification.
      operationId: getHashDetails
      security:
        - accessToken: []
      responses:
        "200":
          description: The hash function information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  lookup_pepper:
                    type: string
                    description: |-
                      The pepper the client MUST use in hashing identifiers, and MUST
                      supply to the `/lookup` endpoint when performing lookups.

                      Servers SHOULD rotate this string often.
                  algorithms:
                    type: array
                    items:
                      type: string
                    description: The algorithms the server supports. Must contain at least `sha256`.
                required:
                  - lookup_pepper
                  - algorithms
              examples:
                response:
                  value: {
                    "lookup_pepper": "matrixrocks",
                    "algorithms": [
                      "none",
                      "sha256"
                    ]
                  }
  /lookup:
    post:
      summary: Look up Matrix User IDs for a set of 3PIDs.
      description: |-
        Looks up the set of Matrix User IDs which have bound the 3PIDs given, if
        bindings are available. Note that the format of the addresses is defined
        later in this specification.
      operationId: lookupUsersV2
      security:
        - accessToken: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                algorithm:
                  type: string
                  description: |-
                    The algorithm the client is using to encode the `addresses`. This
                    should be one of the available options from `/hash_details`.
                  example: sha256
                pepper:
                  type: string
                  description: |-
                    The pepper from `/hash_details`. This is required even when the
                    `algorithm` does not make use of it.
                  example: matrixrocks
                addresses:
                  type: array
                  items:
                    type: string
                  description: |-
                    The addresses to look up. The format of the entries here depend on
                    the `algorithm` used. Note that queries which have been incorrectly
                    hashed or formatted will lead to no matches.

                    Note that addresses are case sensitive: review the
                    [3PID Types](/appendices#3pid-types) to verify the intended case an
                    identifier should be prior to submission/hashing.
                  example:
                    - 4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc
                    - nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I
              required:
                - algorithm
                - pepper
                - addresses
      responses:
        "200":
          description: The associations for any matched `addresses`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mappings:
                    type: object
                    description: |-
                      Any applicable mappings of `addresses` to Matrix User IDs. Addresses
                      which do not have associations will not be included, which can make
                      this property be an empty object.
                    title: AssociatedMappings
                    additionalProperties:
                      type: string
                required:
                  - mappings
              examples:
                response:
                  value: {
                    "mappings": {
                      "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
                    }
                  }
        "400":
          description: |-
            The client's request was invalid in some way. One possible problem could be the `pepper` being invalid after the server has rotated it - this is presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make a call to `/hash_details` to get a new pepper in this scenario, being careful to avoid retry loops.
            `M_INVALID_PARAM` can also be returned to indicate the client supplied an `algorithm` that is unknown to the server.
          content:
            application/json:
              schema:
                $ref: ../client-server/definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_INVALID_PEPPER",
                    "error": "Unknown or invalid pepper - has it been rotated?"
                  }
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8090
      basePath:
        default: /_matrix/identity/v2
components:
  securitySchemes:
    $ref: definitions/security.yaml