start new swagger

2020-08-09 19:03:25 -06:00
parent 02c5d795cf
commit f11261f0da
11 changed files with 275 additions and 2 deletions
--- a/public/swagger/v0/swagger.yaml
+++ b/public/swagger/v0/swagger.yaml
@@ -0,0 +1,174 @@
+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: []