@huynle/hub 0.10.1 → 0.11.1

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

@@ -0,0 +1,119 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Hub API",
+    "version": "1",
+    "description": "The versioned HTTP API of a Hub: every route of the console and agent tables under /api/v1. v1 changes only by addition: clients ignore fields they do not know, treat a value outside an `x-hub-known` list as unknown, and skip a variant of an `x-hub-union` they do not know. Every error is one envelope: {error: {code, message, hint?}}."
+  },
+  "servers": [
+    {
+      "url": "https://hub.example",
+      "description": "A placeholder: the address of your hub."
+    }
+  ],
+  "security": [
+    {
+      "deviceToken": []
+    }
+  ],
+  "components": {
+    "securitySchemes": {
+      "deviceToken": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "A device token: what a native app gets when it redeems a link code (POST /api/v1/devices/redeem). A request with a bearer token needs no Origin."
+      },
+      "deviceCookie": {
+        "type": "apiKey",
+        "in": "cookie",
+        "name": "voice_device",
+        "description": "The browser's credential: the same secret as the device token, as an HttpOnly cookie set when a browser pairs or signs in. A write with the cookie must be same-origin. Send the cookie or a bearer token, never both. Declared here for readers and never listed as a requirement: a generated client sends the bearer token only."
+      }
+    },
+    "responses": {
+      "Error": {
+        "description": "Any error (status 400 and up): the one envelope of /api/v1.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorBody"
+            }
+          }
+        }
+      }
+    },
+    "schemas": {
+      "ErrorBody": {
+        "type": "object",
+        "required": ["error"],
+        "properties": {
+          "error": {
+            "$ref": "#/components/schemas/ErrorDetail"
+          }
+        }
+      },
+      "ErrorDetail": {
+        "type": "object",
+        "description": "What went wrong. A code may come with more fields (for example retryAfter, currentRevision, candidates, feature, limit).",
+        "required": ["code", "message"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Stable and machine-readable. A route that names no code of its own gets one from the status (400 invalid, 401 unauthorized, 403 forbidden, 404 not_found, 408 and 504 timeout, 409 conflict, 410 gone, 413 too_large, 422 unsupported, 429 rate_limited, 500 internal, 502 upstream_failed, 503 unavailable).",
+            "x-hub-known": [
+              "ambiguous",
+              "bad_answer",
+              "bad_bundle",
+              "busy",
+              "changed",
+              "conflict",
+              "developer_off",
+              "dimensions",
+              "expired",
+              "forbidden",
+              "gone",
+              "hidden",
+              "integrity",
+              "internal",
+              "invalid",
+              "invalid_cursor",
+              "limit",
+              "name_taken",
+              "needs_user",
+              "not_exposed",
+              "not_found",
+              "offline",
+              "path",
+              "paused",
+              "plugin_outdated",
+              "rate_limited",
+              "recording_ended",
+              "recording_off",
+              "refused",
+              "timeout",
+              "token_expired",
+              "too_large",
+              "too_old",
+              "type",
+              "unauthorized",
+              "unavailable",
+              "unsupported",
+              "upstream_failed"
+            ]
+          },
+          "message": {
+            "type": "string",
+            "description": "For people."
+          },
+          "hint": {
+            "type": "string",
+            "description": "What to do about it, when the hub knows."
+          }
+        }
+      },
+      "JsonValue": {
+        "description": "Any JSON value: an object, an array, a string, a number, a boolean or null. For data whose shape the hub does not define (a tool's input, a harness's own metadata). Clients map it to their JSON element type."
+      }
+    }
+  }
+}

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>."
+          }
+        }
+      }
+    }
+  }
+}