@huynle/hub 0.11.0 → 0.11.1

package/packages/protocol/schema/api/v1/account.json

@@ -0,0 +1,419 @@
+{
+  "paths": {
+    "/api/v1/auth": {
+      "get": {
+        "operationId": "getAuth",
+        "tags": ["account"],
+        "x-hub-access": "public",
+        "security": [],
+        "summary": "How this hub signs people in",
+        "description": "What a sign-in screen needs before anyone is signed in.",
+        "responses": {
+          "200": {
+            "description": "The hub's sign-in mode.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AuthInfo"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/pair": {
+      "post": {
+        "operationId": "pairDevice",
+        "tags": ["account"],
+        "x-hub-access": "public",
+        "security": [],
+        "summary": "Pair a browser with a pairing code",
+        "description": "Trades a pairing code for a new device, whose secret comes back only as the HttpOnly device cookie (Set-Cookie). For browsers: the request must be same-origin. A native app redeems a link code instead (POST /api/v1/devices/redeem). Fails with 401 unauthorized for an unknown, used or expired code (codes last 5 minutes), 400 invalid for a device name longer than 64 characters, and 429 rate_limited after 10 failed attempts in a minute.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PairRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The new device. Its secret is in the Set-Cookie header, not in the body.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PairedDevice"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/devices/redeem": {
+      "post": {
+        "operationId": "redeemDeviceLink",
+        "tags": ["account"],
+        "x-hub-access": "public",
+        "security": [],
+        "summary": "Trade a link code for a device token",
+        "description": "How a native app signs in: it sends the single-use code of the console's \"Add the Hub app\" link and gets a device token, which it keeps and sends as `Authorization: Bearer`. The request carries no cookie, no bearer token and no Origin; the code is the credential. No cookie is set. Fails with 401 unauthorized for an unknown, used or expired code (codes last 5 minutes) and 400 invalid for a malformed public key (the code stays valid).",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RedeemLinkRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The new device and its token. The token is shown this once.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/LinkedDevice"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/me": {
+      "get": {
+        "operationId": "getMe",
+        "tags": ["account"],
+        "x-hub-access": "user",
+        "summary": "The signed-in device, its user and the hub",
+        "responses": {
+          "200": {
+            "description": "Who is asking, and which hub is answering.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Me"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/devices": {
+      "get": {
+        "operationId": "listDevices",
+        "tags": ["account"],
+        "x-hub-access": "user",
+        "summary": "The user's devices",
+        "responses": {
+          "200": {
+            "description": "Every device of the user: paired browsers and linked apps.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceList"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/devices/link": {
+      "post": {
+        "operationId": "createDeviceLink",
+        "tags": ["account"],
+        "x-hub-access": "user",
+        "summary": "Issue a link code for a native app",
+        "description": "A single-use code that links a new device to the user, shown as a QR code or deep link. The request has no body. The code is redeemed at POST /api/v1/devices/redeem.",
+        "responses": {
+          "200": {
+            "description": "The code and where to redeem it.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceLink"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/devices/{id}": {
+      "delete": {
+        "operationId": "revokeDevice",
+        "tags": ["account"],
+        "x-hub-access": "user",
+        "summary": "Revoke one of the user's devices",
+        "description": "The device's cookie and token stop working. Fails with 404 not_found for an unknown device or another user's.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The device's ID.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Revoked."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/logout": {
+      "post": {
+        "operationId": "logout",
+        "tags": ["account"],
+        "x-hub-access": "user",
+        "summary": "Sign this device out",
+        "description": "Removes the calling device: its cookie and token stop working, and the cookie is cleared (Set-Cookie). The request has no body.",
+        "responses": {
+          "204": {
+            "description": "Signed out."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "AuthInfo": {
+        "type": "object",
+        "required": ["mode", "signIn"],
+        "properties": {
+          "mode": {
+            "type": "string",
+            "description": "pairing: one owner, devices join with a pairing code. oidc: people sign in with the hub's identity provider.",
+            "x-hub-known": ["pairing", "oidc"]
+          },
+          "signIn": {
+            "type": ["string", "null"],
+            "description": "The path on this hub that starts a browser sign-in (oidc), or null (pairing)."
+          }
+        }
+      },
+      "PairRequest": {
+        "type": "object",
+        "required": ["code"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "The 6-digit pairing code. Spaces around it are ignored."
+          },
+          "deviceName": {
+            "type": "string",
+            "description": "A name for the device, 1 to 64 characters after trimming. \"Device\" when absent or empty."
+          }
+        }
+      },
+      "PairedDevice": {
+        "type": "object",
+        "required": ["device"],
+        "properties": {
+          "device": {
+            "$ref": "#/components/schemas/Device"
+          }
+        }
+      },
+      "RedeemLinkRequest": {
+        "type": "object",
+        "required": ["code"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "The link code, from the `code` parameter of the hubapp:// link."
+          },
+          "deviceName": {
+            "type": "string",
+            "description": "A name for the device. Control characters are dropped and it is cut to 64 characters. \"App\" when absent or empty."
+          },
+          "publicKey": {
+            "type": ["string", "null"],
+            "maxLength": 4096,
+            "description": "The public half of the device's signing key, PEM (BEGIN PUBLIC KEY) or its base64 body. Kept with the device for later strong approvals."
+          }
+        }
+      },
+      "LinkedDevice": {
+        "type": "object",
+        "required": ["device", "token"],
+        "properties": {
+          "device": {
+            "$ref": "#/components/schemas/Device"
+          },
+          "token": {
+            "type": "string",
+            "description": "The device token: the app's credential, sent as `Authorization: Bearer`."
+          }
+        }
+      },
+      "Device": {
+        "type": "object",
+        "required": ["id", "name", "created", "lastSeen"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "created": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was paired or linked, in epoch milliseconds."
+          },
+          "lastSeen": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the hub last saw it, in epoch milliseconds."
+          }
+        }
+      },
+      "User": {
+        "type": "object",
+        "required": ["id", "role"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "\"local\" for the owner of a pairing-mode hub."
+          },
+          "email": {
+            "type": "string",
+            "description": "Absent for the owner of a pairing-mode hub."
+          },
+          "name": {
+            "type": "string",
+            "description": "Absent when the identity provider gave none."
+          },
+          "role": {
+            "type": "string",
+            "x-hub-known": ["admin", "user"]
+          }
+        }
+      },
+      "Me": {
+        "type": "object",
+        "required": ["device", "user", "auth", "publicURL", "version"],
+        "properties": {
+          "device": {
+            "$ref": "#/components/schemas/Device"
+          },
+          "user": {
+            "$ref": "#/components/schemas/User"
+          },
+          "auth": {
+            "type": "string",
+            "description": "The hub's sign-in mode, as in AuthInfo.mode.",
+            "x-hub-known": ["pairing", "oidc"]
+          },
+          "publicURL": {
+            "type": "string",
+            "description": "The address the hub is reached at, without a trailing slash."
+          },
+          "version": {
+            "type": "string",
+            "description": "The hub's version."
+          }
+        }
+      },
+      "ListedDevice": {
+        "type": "object",
+        "description": "A device in the user's list: a Device, and whether it is the one asking.",
+        "required": ["id", "name", "created", "lastSeen", "current"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "created": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was paired or linked, in epoch milliseconds."
+          },
+          "lastSeen": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the hub last saw it, in epoch milliseconds."
+          },
+          "current": {
+            "type": "boolean",
+            "description": "True for the device that made this request."
+          }
+        }
+      },
+      "DeviceList": {
+        "type": "object",
+        "required": ["devices"],
+        "properties": {
+          "devices": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ListedDevice"
+            }
+          }
+        }
+      },
+      "DeviceLink": {
+        "type": "object",
+        "required": ["code", "expiresAt", "hub", "url"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "The single-use link code."
+          },
+          "expiresAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the code stops working, in epoch milliseconds (5 minutes after it was issued)."
+          },
+          "hub": {
+            "type": "string",
+            "description": "The hub's public address, where the app redeems the code."
+          },
+          "url": {
+            "type": "string",
+            "description": "The deep link to show as a QR code: hubapp://link?hub=<hub>&code=<code>."
+          }
+        }
+      }
+    }
+  }
+}