.. SPDX-FileCopyrightText: © 2024 Matt Williams <matt.williams@bristol.ac.uk>
   SPDX-License-Identifier: CC-BY-SA-4.0

HTTP API
========

Conch provides a HTTP API to perform signing requests.

.. http:get:: /sign

   Sign a public SSH key, using the provided JWT to authorise.

   **Example request**:

   .. sourcecode:: http

      GET /sign?public_key=ssh-ed25519%20AAAAC3NzaC1lZ<example-snipped> HTTP/1.1
      Host: example.com
      Accept: application/json
      Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cC<example snipped>

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "resources": {
          "batch.cluster1.example": {
            "alias": "cluster1.example",
            "hostname": "1.access.example.com",
            "proxy_jump": "bastion.example.com"
          },
          "batch.cluster2.example": {
            "alias": "cluster2.example",
            "hostname": "2.access.example.com",
            "proxy_jump": "bastion.example.com"
          }
        },
        "associations": {
          "project-a": {
            "name": "Project A",
            "resources": {
              "batch.cluster1.example": {
                "username": "user.proj-a",
                "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
              },
              "batch.cluster2.example": {
                "username": "user.proj-a",
                "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
              }
            }
          },
          "project-b": {
            "name": "Project B",
            "resources": {
              "batch.cluster2.example": {
                "username": "user.proj-b",
                "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
              }
            }
          }
        },
        "user": "test@example.com",
        "version": 3
      }

   :query string public_key: the SSH public key to sign

   :<header Authorization: an OIDC access token in JWT form. See :ref:`claims` for more information on the contents.

   :>json Resources resources: the resources the certificate can be used on. See :confval:`resources` for the structure.
   :>json Associations associations:
      The associations between the resources and their projects or user details.

      Depending on the value of :confval:`mapper`, the contents of this will vary:

      :confval:`single`/:confval:`per_resource`:
         .. sourcecode:: json

            "associations": {
              "resources": {
                "batch.cluster1.example": {
                  "username": "foo",
                  "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
                },
                "batch.cluster2.example": {
                  "username": "bar",
                  "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
                }
              }
            }

      :confval:`project_infra` ``v1``:
         .. sourcecode:: json

            "associations": {
              "project-a": {
                "name": "Project A",
                "resources": {
                  "batch.cluster1.example": {
                    "username": "user.proj-a",
                    "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
                  },
                  "batch.cluster2.example": {
                    "username": "user.proj-a",
                    "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
                  }
                }
              },
              "project-b": {
                "name": "Project B",
                "resources": {
                 "batch.cluster2.example": {
                   "username": "user.proj-b",
                    "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAIHNzaC<example snipped>"
                  }
                }
              }
            },
   :>json string user: the email address of the user
   :>json integer version: the version of the response. Currently ``3``.

.. http:get:: /issuer

   .. deprecated:: 0.3

      Use :http:get:`/oidc` instead.

   Get the URL of the OIDC issuer.

   **Example request**:

   .. sourcecode:: http

      GET /issuer HTTP/1.1
      Host: example.com

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      https://keycloak.example.com/realms/example

.. http:get:: /oidc

   .. versionadded:: 0.3

   Get the details of the OIDC issuer and client information to use.

   **Example request**:

   .. sourcecode:: http

      GET /client_id HTTP/1.1
      Host: example.com

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "issuer": "https://keycloak.example.com/realms/example",
        "client_id": "clifton",
        "version": 1
      }

   :>json string issuer: the URL of the OIDC issuer.
   :>json string client_id: the ID of the OIDC client to use when talking to the issuer.
   :>json integer version: the version of the response. Currently ``1``.

.. http:get:: /public_key

   .. versionadded:: 0.2

   Get the public part of the currently used signing key.

   **Example request**:

   .. sourcecode:: http

      GET /public_key HTTP/1.1
      Host: example.com

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBsaKBqZPg<example snipped>

.. http:get:: /health

   .. versionadded:: 0.1.3

   Check the health of the service.

   **Example request**:

   .. sourcecode:: http

      GET /health HTTP/1.1
      Host: example.com

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {}

   :statuscode 200: Conch is running and working.