@fleetless/contracts 1.0.0

package/artifacts/schema/mcp-robot-datasheet.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "robot_id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "robot_name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "action_history": {
+          "type": "boolean"
+        },
+        "assets": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "action_history",
+        "assets"
+      ],
+      "additionalProperties": false
+    },
+    "exposures": {
+      "maxItems": 2000,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 63,
+            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "datapoint",
+              "service",
+              "action",
+              "publisher",
+              "camera"
+            ]
+          },
+          "description": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 2000
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "unit": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 32
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "decimals": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 6
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "input_schema": {
+            "anyOf": [
+              {},
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "slug",
+          "kind",
+          "description",
+          "unit",
+          "decimals",
+          "input_schema"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "robot_id",
+    "robot_name",
+    "capabilities",
+    "exposures"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/mcp-role-preview-response.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "role_id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "robots": {
+      "maxItems": 500,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "robot_id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          },
+          "robot_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "capabilities": {
+            "type": "object",
+            "properties": {
+              "action_history": {
+                "type": "boolean"
+              },
+              "assets": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "action_history",
+              "assets"
+            ],
+            "additionalProperties": false
+          },
+          "exposures": {
+            "maxItems": 2000,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "slug": {
+                  "type": "string",
+                  "minLength": 2,
+                  "maxLength": 63,
+                  "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                },
+                "kind": {
+                  "type": "string",
+                  "enum": [
+                    "datapoint",
+                    "service",
+                    "action",
+                    "publisher",
+                    "camera"
+                  ]
+                },
+                "description": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 2000
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "unit": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 32
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "decimals": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 6
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "input_schema": {
+                  "anyOf": [
+                    {},
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "slug",
+                "kind",
+                "description",
+                "unit",
+                "decimals",
+                "input_schema"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "robot_id",
+          "robot_name",
+          "capabilities",
+          "exposures"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "role_id",
+    "robots"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/missing-asset-query.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "The unresolved reference, as the URDF spelled it, echoed into the `404 asset_missing` message. Omitted, the message names `unknown` instead. It never changes the status.",
+      "type": "string"
+    }
+  },
+  "description": "The one optional parameter of the missing-asset placeholder; it names the reference in the refusal."
+}

package/artifacts/schema/oauth-authorize-query.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "response_type": {
+      "type": "string",
+      "const": "code",
+      "description": "Always `code`. RFC 6749 §4.1.2.1 names `unsupported_response_type` for any other value, but `oauthErrorCode` has no such member — this server issues no other grant from this endpoint — so an unsupported value comes back on the callback as `invalid_request`."
+    },
+    "client_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The OAuth client, self-registered or the one well-known central client — **not** the app identifier. Unknown, expired-dynamic and mismatched clients all collapse into the same `400 invalid_client`, answered without a redirect."
+    },
+    "redirect_uri": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One of the client's registered redirect URIs, compared **exactly** — string equality against the registered list, never a prefix or a host match. Both the shape (`redirectUri`) and the registration are checked, and a failure of either is a `400 invalid_request` with no redirect."
+    },
+    "code_challenge": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The PKCE challenge; the verifier is presented at the token endpoint. Only non-emptiness is checked here — length and alphabet are not — since the verifier is what actually has to match."
+    },
+    "code_challenge_method": {
+      "type": "string",
+      "const": "S256",
+      "description": "Only `S256`. `plain` is refused: a challenge equal to its verifier defends against nothing."
+    },
+    "state": {
+      "description": "Returned unchanged on the callback, and on the error redirect too, so a client can bind either answer to its own request.",
+      "type": "string"
+    },
+    "resource": {
+      "description": "RFC 8707 resource indicator: the API origin or the MCP endpoint the token is for. Checked against the resources this server issues tokens for **on behalf of this client's app**; a mismatch is `invalid_target` on the callback.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "response_type",
+    "client_id",
+    "redirect_uri",
+    "code_challenge",
+    "code_challenge_method"
+  ],
+  "description": "The authorization request an MCP client sends, per RFC 6749 §4.1.1 with mandatory PKCE. The handler reads it parameter by parameter rather than through one parse, because the answers differ: `client_id` and `redirect_uri` are refused flat, with no redirect, since until both are confirmed there is no trusted target to bounce a browser to, and everything after them is reported to the client's own callback as query parameters."
+}

package/artifacts/schema/oauth-redirect-response.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "redirect_to": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000
+    }
+  },
+  "required": [
+    "redirect_to"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/oauth-token-request.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "grant_type": {
+      "type": "string",
+      "const": "authorization_code",
+      "description": "Always `authorization_code`: this request exchanges the code from the authorize redirect for tokens. Any other value — `refresh_token` included — is `unsupported_grant_type`, refused before the code is looked up."
+    },
+    "code": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "The authorization code from the redirect. It may be exchanged once; a second presentation is `invalid_grant`, the same answer a fabricated code gets."
+    },
+    "redirect_uri": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "description": "The same redirect URI the authorize request used. It is compared, not merely recorded."
+    },
+    "client_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "The client making the exchange, as registered."
+    },
+    "code_verifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9\\-._~]{43,128}$",
+      "description": "The PKCE verifier whose `S256` hash was sent as the challenge at the authorize step. Between `43` and `128` unreserved characters, per RFC 7636 §4.1 — it is compared rather than parsed, so a length nobody checks is a length an attacker chooses. PKCE is mandatory for every client under OAuth 2.1."
+    },
+    "resource": {
+      "description": "The resource the token is being requested for, per RFC 8707. It must match the audience the code was authorized for, or the answer is `invalid_target`; omitted, the code's own audience stands. It becomes the token's `aud`, and a resource refuses a token whose audience names something else — which is what keeps a token minted for one app out of another app's endpoint.",
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "required": [
+    "grant_type",
+    "code",
+    "redirect_uri",
+    "client_id",
+    "code_verifier"
+  ],
+  "description": "RFC 6749 §4.1.3's authorization-code exchange with PKCE, as either MCP authorization server reads it. Sent as `application/x-www-form-urlencoded`, per §4.1.3, though the server accepts a JSON body too."
+}

package/artifacts/schema/oauth-token-response.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "access_token": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The bearer token. It is the same token the client login mints — only the envelope differs, because an RFC-compliant client parses this one and knows nothing about Fleetless."
+    },
+    "token_type": {
+      "type": "string",
+      "const": "Bearer",
+      "description": "`Bearer`. RFC 6749 §5.1 makes the value case-insensitive for a client reading it; this is the spelling this server emits."
+    },
+    "expires_in": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "description": "How long the access token is valid, in **seconds**, per RFC 6749 §5.1. Not a timestamp, and not milliseconds."
+    },
+    "refresh_token": {
+      "description": "The refresh token, when one was issued. It rotates on every use.",
+      "type": "string",
+      "minLength": 1
+    },
+    "scope": {
+      "description": "The scopes the issued token actually carries, space-separated.",
+      "type": "string",
+      "maxLength": 500
+    }
+  },
+  "required": [
+    "access_token",
+    "token_type",
+    "expires_in"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/org-alerts-query.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "state": {
+      "type": "string",
+      "const": "firing",
+      "description": "Required, and the only accepted value — this endpoint lists the alerts that are firing now. Anything else, the parameter's absence included, is `400 validation_error`: a door with one answer must not advertise a dial."
+    }
+  },
+  "required": [
+    "state"
+  ],
+  "description": "The query of `GET /api/org/alerts`. One required parameter with one accepted value."
+}

package/artifacts/schema/org-event-dropped.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "org_event_dropped"
+    },
+    "since_ms": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "dropped": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    }
+  },
+  "required": [
+    "type",
+    "since_ms",
+    "dropped"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/org-event-replay.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "org_event_replay"
+    },
+    "events": {
+      "maxItems": 200,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "const": "org_event"
+          },
+          "seq": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "at": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "datapoint",
+              "health",
+              "job",
+              "bridge",
+              "audit",
+              "alert"
+            ]
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "info",
+              "warning",
+              "error"
+            ]
+          },
+          "robot_id": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "uuid",
+                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "subject": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "detail": {
+            "anyOf": [
+              {},
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "type",
+          "seq",
+          "at",
+          "kind",
+          "severity",
+          "robot_id",
+          "subject",
+          "detail"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "complete": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "type",
+    "events",
+    "complete"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/org-event-subscribe.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "org_event_subscribe"
+    }
+  },
+  "required": [
+    "type"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/org-event-unsubscribe.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "org_event_unsubscribe"
+    }
+  },
+  "required": [
+    "type"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/org-event.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "org_event"
+    },
+    "seq": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "datapoint",
+        "health",
+        "job",
+        "bridge",
+        "audit",
+        "alert"
+      ]
+    },
+    "severity": {
+      "type": "string",
+      "enum": [
+        "info",
+        "warning",
+        "error"
+      ]
+    },
+    "robot_id": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "subject": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "detail": {
+      "anyOf": [
+        {},
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "seq",
+    "at",
+    "kind",
+    "severity",
+    "robot_id",
+    "subject",
+    "detail"
+  ],
+  "additionalProperties": false
+}