openapi: 3.0.2
info:
  title: DnDex
  description: |
    DnD indexing, pronounced dee-in-dex

    UI via http://ui.dndex.lan:8080/, API via http://api.dndex.lan:8080/

    Sources
    * <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#referenceObject">OpenAPI</a>
    * <a href="http://api.dndex.lan:8080/__files__/swagger/swagger.html#/">Swagger UI</a>
  version: 0.0.2

servers:
- url: http://api.dndex.lan:8080/
- url: http://authapi.dndex.lan:8080/

paths:
  /who:
    $ref: "./swagger-who.yaml#/paths"
  /register:
    $ref: "./swagger-register.yaml#/paths"
  /port:
    $ref: "./swagger-port.yaml#/paths"
  /__files__/{namespace}/{path}:
    $ref: "./swagger-files.yaml#/paths"

components:
  parameters:
    namespace:
      name: namespace
      in: query
      required: true
      description: "An authorized universe"
      schema:
        type: string

    path:
      name: path
      in: path
      required: true
      schema:
        type: string

    namespacePath:
      name: namespace
      in: path
      required: true
      schema:
        type: string

  schemas:
    ok:
      content:
        application/json:
            properties:
              status:
                type: string
                example: "ok"

    one:
      title: "One entity"
      type: object
      properties:
        name:
          type: string
          example: "Jeff Snow"
        type:
          type: string
          example: "doggo"
        title:
          type: string
          example: "Meme Lord"
        text:
          type: string
          example: "Lorem ipsum"
        relationship:
          type: string
          example: "Good boi"
        modified:
          type: int
          example: 8675309
        attachments:
          type: object
          additionalProperties:
            type: string
        connections:
          type: object
          additionalProperties:
            type: object

  securitySchemes:
    token:
      type: apiKey
      description: |
        Disabled by default but required by all endpoints when enabled

        Provided as AES-GCM 12-byte-padded ciphertext on all unauthorized requests via the header "Set-Cookie:New-DnDex-Auth=encode-token"

        <details>
        <summary>
        [Code example of decrypting a token in Javascript](https://notes-server.remote.blapointe.com/notes/disciplines/tech/languages/Encryption.md#toc_1)
        </summary>
        ```javascript
          class NewAuthToken {
              constructor(key) {
                  if (!key) {
                      throw "invalid key"
                  }
                  this.key = key.repeat(32).substr(0, 32)
              }

              decode(b64, callback) {
                  var ciphertext = this.base64_decode(b64)

                  var iv = ciphertext.substr(0, 12)
                  var encrypted = ciphertext.substr(iv.length, ciphertext.length-iv.length)

                  this.get_crypto_key()
                      .then(function(crypto_key) {
                          NewAuthToken.decrypt(crypto_key, iv, encrypted, callback)
                      })
              }

              base64_decode(b64) {
                  return atob(b64)
              }

              static to_buffer(s) {
                  var bytes = new Uint8Array(s.length)
                  for (var i = 0; i < s.length; i++) {
                     bytes[i] = s.charCodeAt(i)
                  }
                  return bytes.buffer
              }

              static decrypt(crypto_key, iv, encrypted, callback) {
                  window.crypto.subtle.decrypt(
                     {name: "AES-GCM", iv: NewAuthToken.to_buffer(iv)},
                     crypto_key,
                     NewAuthToken.to_buffer(encrypted),
                  )
                      .then(function(decrypted) {
                          callback(String.fromCharCode.apply(null, new Uint8Array(decrypted)))
                      })
              }

              get_crypto_key() {
                  return crypto.subtle.importKey(
                      "raw",
                      NewAuthToken.to_buffer(this.key),
                      "AES-GCM",
                      false,
                      ["decrypt"]
                  )
              }

              set_token(encoded_token) {
                  this.decode(encoded_token, function (token) {
                      console.log("Set-Cookie DnDex-Auth="+token)
                      document.cookie = "DnDex-Auth=" + token + ";path=/"
                  })
              }
          }

          authtoken = new NewAuthToken("123").set_token("SOY05yF/9iv3YG71sKkQPVaEwO53PCX8qZhDHS9JUohBgVl5Qr9/GTKK/TJ6OozhHN7QBIGmHNzQxTRRSLs4Lw==")
        ```
        </details>
      name: DnDex-Auth
      in: cookie

security:
- {}
- token: []