dndex/public/swagger/v1/swagger.yaml

openapi: 3.0.2
info:
  title: DnDex
  description: |
    DnDex API, pronounced dee-IN-dex

    UI via htp://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.1.0

servers:
- url: http://api1.dndex.lan:8080/

paths:
  /api/version:
    $ref: "./version.yaml#/paths"
  /api/dump:
    $ref: "./dump.yaml#/paths"
  /api/files:
    $ref: "./files/index.yaml#/paths"
  /api/files/{path}:
    $ref: "./files/one.yaml#/paths"
  /api/users/register:
    $ref: "./users/register.yaml#/paths"
  /api/users/login:
    $ref: "./users/login.yaml#/paths"
  /api/entities:
    $ref: "./entities/index.yaml#/paths"
  /api/entities/{id}:
    $ref: "./entities/id.yaml#/paths"
  /api/entities/{id}/{path}:
    $ref: "./entities/idsub.yaml#/paths"
  /:
    $ref: "./index.yaml#/paths"

components:
  parameters:
    id:
      name: id
      in: path
      required: true
      schema:
        type: string

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

    token:
      name: DnDex-Auth
      in: cookie
      required: true
      schema:
        type: string

  schemas:
    responseOneResolved:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/objectOneResolved"

    responseOne:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/objectOne"

    responseOK:
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
                example: true

    fullList:
      content:
        application/json:
          schema:
            type: object
            properties:
              namespace:
                type: array
                items:
                  $ref: "#/components/schemas/objectOne"

    responseShortList:
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                Name: string
                ID: string
              example:
                Name: Jeff Snow
                ID: abc-123-def-456

    requestForm:
      content:
        application/x-www-form-urlencoded:
          schema:
            type: string
            example: http://imgur.com/big-tiddy-goth-gf.jpg

    requestOne:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/objectOne"

    oneID:    { type: string, example: "abc-123-def-456" }
    oneName:  { type: string, example: "Jeff Snow" }
    oneType:  { type: string, example: "Doggo" }
    oneTitle:  { type: string, example: "Meme Lord" }
    oneText:   { type: string, example: "Lorem ipsum" }
    oneModified:   { type: int, example: 1234567890 }
    oneAttachments:
      type: object
      additionalProperties:
        type: object
        properties:
          location:
            type: string
      example:
        "abc-123-def-456":
          location: "/__files__/my/file.txt"

    objectOneResolved:
      type: object
      properties:
        _id: { $ref: "#/components/schemas/oneID" }
        name: { $ref: "#/components/schemas/oneName" }
        type: { $ref: "#/components/schemas/oneType" }
        title: { $ref: "#/components/schemas/oneTitle" }
        text: { $ref: "#/components/schemas/oneText" }
        modified: { $ref: "#/components/schemas/oneModified" }
        attachments: { $ref: "#/components/schemas/oneAttachments" }
        connections:
          type: object
          additionalProperties: { $ref: "#/components/schemas/objectOne" }

    objectOne:
      type: object
      properties:
        _id: { $ref: "#/components/schemas/oneID" }
        name: { $ref: "#/components/schemas/oneName" }
        type: { $ref: "#/components/schemas/oneType" }
        title: { $ref: "#/components/schemas/oneTitle" }
        text: { $ref: "#/components/schemas/oneText" }
        modified: { $ref: "#/components/schemas/oneModified" }
        attachments: { $ref: "#/components/schemas/oneAttachments" }
        connections:
          type: object
          additionalProperties:
            type: object
            properties:
              relationship:
                type: string
          example:
            "abc-123-def-456":
              relationship: "friendly"

  securitySchemes:
    token:
      name: DnDex-Auth
      in: cookie
      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 a response to a `/users/login` request.

        <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>        

security:
- {}
- token: []