# 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 Terms of Service API
  version: 2.0.0
paths:
  /terms:
    get:
      summary: Gets the terms of service offered by the server.
      description: |-
        Gets all the terms of service offered by the server. The client is expected
        to filter through the terms to determine which terms need acceptance from the
        user. Note that this endpoint does not require authentication.
      operationId: getTerms
      responses:
        "200":
          description: The terms of service offered by the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  policies:
                    type: object
                    title: Policy Map
                    description: |-
                      The policies the server offers. Mapped from arbitrary ID (unused in
                      this version of the specification) to a Policy Object.
                    additionalProperties:
                      type: object
                      title: Policy Object
                      description: |-
                        The policy. Includes a map of language (ISO 639-2) to language-specific
                        policy information.
                      properties:
                        version:
                          type: string
                          description: |-
                            The version for the policy. There are no requirements on what this
                            might be and could be "alpha", semantically versioned, or arbitrary.
                      required:
                        - version
                      additionalProperties:
                        type: object
                        title: Internationalised Policy
                        description: The policy information for the specified language.
                        properties:
                          name:
                            type: string
                            description: The translated name of the policy.
                          url:
                            type: string
                            description: |-
                              The URL, which should include the policy ID, version, and language
                              in it, to be presented to the user as the policy. URLs should have
                              all three criteria to avoid conflicts when the policy is updated
                              in the future: for example, if this was "https://example.org/terms.html"
                              then the server would be unable to update it because the client would
                              have already added that URL to the `m.accepted_terms` collection.
                        required:
                          - name
                          - url
                required:
                  - policies
              examples:
                response:
                  value: {
                    "policies": {
                      "terms_of_service": {
                        "version": "2.0",
                        "en": {
                          "name": "Terms of Service",
                          "url": "https://example.org/somewhere/terms-2.0-en.html"
                        },
                        "fr": {
                          "name": "Conditions d'utilisation",
                          "url": "https://example.org/somewhere/terms-2.0-fr.html"
                        }
                      },
                      "privacy_policy": {
                        "version": "1.2",
                        "en": {
                          "name": "Privacy Policy",
                          "url": "https://example.org/somewhere/privacy-1.2-en.html"
                        },
                        "fr": {
                          "name": "Politique de confidentialité",
                          "url": "https://example.org/somewhere/privacy-1.2-fr.html"
                        }
                      }
                    }
                  }
    post:
      summary: Indicates acceptance of terms to the server.
      description: |-
        Called by a client to indicate that the user has accepted/agreed to the included
        set of URLs. Servers MUST NOT assume that the client will be sending all previously
        accepted URLs and should therefore append the provided URLs to what the server
        already knows has been accepted.

        Clients MUST provide the URL of the policy in the language that was presented
        to the user. Servers SHOULD consider acceptance of any one language's URL as
        acceptance for all other languages of that policy.

        The server should avoid returning `M_TERMS_NOT_SIGNED` because the client
        may not be accepting all terms at once.
      operationId: agreeToTerms
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_accepts:
                  type: array
                  items:
                    type: string
                  description: The URLs the user is accepting in this request.
                  example: ["https://example.org/somewhere/terms-2.0-en.html"]
              required:
                - user_accepts
      responses:
        "200":
          description: The server has considered the user as having accepted the provided
            URLs.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  value: {}
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8090
      basePath:
        default: /_matrix/identity/v2
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer