@fleetless/contracts 5.2.0 → 6.0.0-next.1

package/artifacts/schema/client-sign-in-result.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "anyOf": [
+    {
+      "type": "object",
+      "properties": {
+        "access_token": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The token to send as `Authorization: Bearer <token>` on every call. Short-lived: read `expires_in` rather than assuming a lifetime."
+        },
+        "refresh_token": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The token that buys the next access token. It rotates on every use, so a value presented twice is detectable theft and ends the whole family."
+        },
+        "expires_in": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991,
+          "description": "How long the access token stays valid, in **seconds** from now. Not a timestamp, and not milliseconds."
+        }
+      },
+      "required": [
+        "access_token",
+        "refresh_token",
+        "expires_in"
+      ],
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "two_factor_required",
+            "two_factor_setup_required"
+          ],
+          "description": "`two_factor_required`: ask for the authenticator code. `two_factor_setup_required`: the app requires two-factor and the person has none yet, so set one up before any session exists."
+        },
+        "challenge": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The handle the next step spends. Valid five minutes; afterwards it answers `410 token_spent` and the sign-in starts over."
+        }
+      },
+      "required": [
+        "status",
+        "challenge"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}

package/artifacts/schema/client-two-factor-disable-request.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^\\d{6}$",
+      "description": "A code the authenticator shows now."
+    }
+  },
+  "required": [
+    "code"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/client-two-factor-setup-confirm-request.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "challenge": {
+      "description": "The same challenge as at `setup`, during sign-in; absent with a bearer.",
+      "type": "string",
+      "minLength": 1
+    },
+    "code": {
+      "type": "string",
+      "pattern": "^\\d{6}$",
+      "description": "A code the new authenticator shows now. It proves the secret was copied correctly before anything depends on it."
+    }
+  },
+  "required": [
+    "code"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/client-two-factor-setup-confirm-response.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "recovery_codes": {
+      "minItems": 10,
+      "maxItems": 10,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z2-7]{5}-[a-z2-7]{5}$"
+      },
+      "description": "The ten single-use recovery codes, lowercase, shown once. Any earlier set is void."
+    },
+    "session": {
+      "type": "object",
+      "properties": {
+        "access_token": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The token to send as `Authorization: Bearer <token>` on every call. Short-lived: read `expires_in` rather than assuming a lifetime."
+        },
+        "refresh_token": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The token that buys the next access token. It rotates on every use, so a value presented twice is detectable theft and ends the whole family."
+        },
+        "expires_in": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991,
+          "description": "How long the access token stays valid, in **seconds** from now. Not a timestamp, and not milliseconds."
+        }
+      },
+      "required": [
+        "access_token",
+        "refresh_token",
+        "expires_in"
+      ],
+      "additionalProperties": false,
+      "description": "The session the sign-in was waiting for, or a fresh one for the account settings."
+    }
+  },
+  "required": [
+    "recovery_codes",
+    "session"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/client-two-factor-setup-request.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "challenge": {
+      "description": "The `two_factor_setup_required` challenge, during sign-in. Absent when the call carries the app user's bearer instead.",
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "additionalProperties": false
+}

package/artifacts/schema/client-two-factor-verify-request.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "challenge": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The challenge the sign-in step answered."
+    },
+    "code": {
+      "description": "The six-digit code the authenticator shows now. A code already accepted once is refused, so a replay of a seen code does not sign anybody in.",
+      "type": "string",
+      "pattern": "^\\d{6}$"
+    },
+    "recovery_code": {
+      "description": "One of the ten recovery codes, `xxxxx-xxxxx`, in either case. Spent by its use.",
+      "type": "string",
+      "pattern": "^[a-zA-Z2-7]{5}-[a-zA-Z2-7]{5}$"
+    }
+  },
+  "required": [
+    "challenge"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/create-app-invitation-request.schema.json

@@ -29,7 +29,7 @@
     },
     "send_mail": {
       "type": "boolean",
-      "description": "Whether Fleetless mails the invitation. **Refused with `409 target_state_conflict` naming `invite_url` when the app has configured none** — there would be nowhere for the link to point, and a mail carrying a Fleetless-hosted page is a surface this product does not have."
+      "description": "Whether Fleetless mails the invitation. The link points at the app's `invite_url`, or at the Fleetless-hosted invitation page when the app has configured none — so the mail always leads somewhere, and nothing is refused for a missing URL."
     }
   },
   "required": [

package/artifacts/schema/create-passkey-request.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "What to call the passkey, such as the device it lives on."
+    },
+    "credential": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {},
+      "description": "The browser's `RegistrationResponseJSON` for the options `POST /api/auth/passkeys/options` answered."
+    }
+  },
+  "required": [
+    "name",
+    "credential"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/create-passkey-response.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "passkey": {
+      "type": "object",
+      "properties": {
+        "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)$",
+          "description": "The passkey in the API, as renamed and removed through `/api/auth/passkeys/:id`."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80,
+          "description": "What the person called it, such as the device it lives on."
+        },
+        "created_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))$",
+          "description": "When it was registered."
+        },
+        "last_used_at": {
+          "anyOf": [
+            {
+              "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))$"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When it last signed the person in or confirmed a sign-in, or `null` if never."
+        },
+        "synced": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Whether the authenticator reported the passkey as syncable across the person's devices (the backup-eligible flag), or `null` when it said nothing."
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "created_at",
+        "last_used_at",
+        "synced"
+      ],
+      "additionalProperties": false,
+      "description": "The passkey as it is now stored."
+    },
+    "recovery_codes": {
+      "anyOf": [
+        {
+          "minItems": 10,
+          "maxItems": 10,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z2-7]{5}-[a-z2-7]{5}$"
+          }
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The ten recovery codes, shown once, when this passkey is the account's first second factor; `null` when the account already had one and its codes stay valid."
+    }
+  },
+  "required": [
+    "passkey",
+    "recovery_codes"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/developer-passkey.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "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)$",
+      "description": "The passkey in the API, as renamed and removed through `/api/auth/passkeys/:id`."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "What the person called it, such as the device it lives on."
+    },
+    "created_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))$",
+      "description": "When it was registered."
+    },
+    "last_used_at": {
+      "anyOf": [
+        {
+          "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))$"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "When it last signed the person in or confirmed a sign-in, or `null` if never."
+    },
+    "synced": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Whether the authenticator reported the passkey as syncable across the person's devices (the backup-eligible flag), or `null` when it said nothing."
+    }
+  },
+  "required": [
+    "id",
+    "name",
+    "created_at",
+    "last_used_at",
+    "synced"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/developer-two-factor.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "passkeys": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "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)$",
+            "description": "The passkey in the API, as renamed and removed through `/api/auth/passkeys/:id`."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 80,
+            "description": "What the person called it, such as the device it lives on."
+          },
+          "created_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))$",
+            "description": "When it was registered."
+          },
+          "last_used_at": {
+            "anyOf": [
+              {
+                "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))$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "When it last signed the person in or confirmed a sign-in, or `null` if never."
+          },
+          "synced": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Whether the authenticator reported the passkey as syncable across the person's devices (the backup-eligible flag), or `null` when it said nothing."
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "created_at",
+          "last_used_at",
+          "synced"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Every passkey the caller has registered, oldest first. Empty when none."
+    },
+    "authenticator": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "created_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))$",
+              "description": "When the authenticator was confirmed."
+            }
+          },
+          "required": [
+            "created_at"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The confirmed authenticator app, or `null` when there is none. At most one."
+    },
+    "recovery_codes_left": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 10,
+      "description": "How many of the ten recovery codes are unspent. `0` while the caller has no second factor."
+    },
+    "required_by_org": {
+      "type": "boolean",
+      "description": "Whether the organisation requires a second factor. While it does, the last one cannot be removed."
+    }
+  },
+  "required": [
+    "passkeys",
+    "authenticator",
+    "recovery_codes_left",
+    "required_by_org"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/fleetless-user-list-response.schema.json

@@ -46,6 +46,27 @@
             ],
             "description": "The console powers this person holds. **Required** — every Fleetless user has a tier; it was optional only while the org also held people with no console powers to grade, and that pool is gone."
           },
+          "two_factor": {
+            "type": "object",
+            "properties": {
+              "passkeys": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "How many passkeys the person has registered."
+              },
+              "authenticator": {
+                "type": "boolean",
+                "description": "Whether the person has a confirmed authenticator app."
+              }
+            },
+            "required": [
+              "passkeys",
+              "authenticator"
+            ],
+            "additionalProperties": false,
+            "description": "The person's second factors, as the team list shows them: none, passkeys, an authenticator, or both. No credential travels here. An owner resets them through `DELETE /api/org/users/:id/two-factor`."
+          },
           "created_at": {
             "type": "string",
             "format": "date-time",
@@ -59,6 +80,7 @@
           "email",
           "display_name",
           "tier",
+          "two_factor",
           "created_at"
         ],
         "additionalProperties": false

package/artifacts/schema/fleetless-user.schema.json

@@ -41,6 +41,27 @@
       ],
       "description": "The console powers this person holds. **Required** — every Fleetless user has a tier; it was optional only while the org also held people with no console powers to grade, and that pool is gone."
     },
+    "two_factor": {
+      "type": "object",
+      "properties": {
+        "passkeys": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "How many passkeys the person has registered."
+        },
+        "authenticator": {
+          "type": "boolean",
+          "description": "Whether the person has a confirmed authenticator app."
+        }
+      },
+      "required": [
+        "passkeys",
+        "authenticator"
+      ],
+      "additionalProperties": false,
+      "description": "The person's second factors, as the team list shows them: none, passkeys, an authenticator, or both. No credential travels here. An owner resets them through `DELETE /api/org/users/:id/two-factor`."
+    },
     "created_at": {
       "type": "string",
       "format": "date-time",
@@ -54,6 +75,7 @@
     "email",
     "display_name",
     "tier",
+    "two_factor",
     "created_at"
   ],
   "additionalProperties": false

package/artifacts/schema/invalid-code-details.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "attempts_left": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "How many more wrong codes this code or challenge takes before it is spent. `0` means the next attempt answers `410 token_spent`."
+    }
+  },
+  "required": [
+    "attempts_left"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/org.schema.json

@@ -14,6 +14,10 @@
       "maxLength": 120,
       "description": "The organisation's display name. Free text, changed through `PATCH /api/org`."
     },
+    "require_two_factor": {
+      "type": "boolean",
+      "description": "Whether every member must have a second factor — a passkey or an authenticator app. A member without one sets it up at their next sign-in, before any session exists; nobody is signed out when it is switched on. It covers the console and the central MCP endpoint; server keys and robot bridges are not people and are not affected. Owners change it through `PATCH /api/org`."
+    },
     "created_at": {
       "type": "string",
       "format": "date-time",
@@ -24,6 +28,7 @@
   "required": [
     "id",
     "name",
+    "require_two_factor",
     "created_at"
   ],
   "additionalProperties": false

package/artifacts/schema/patch-org-request.schema.json

@@ -3,13 +3,15 @@
   "type": "object",
   "properties": {
     "name": {
+      "description": "The organisation's new display name. Absent leaves it alone.",
       "type": "string",
       "minLength": 1,
       "maxLength": 120
+    },
+    "require_two_factor": {
+      "description": "Whether every member must have a second factor. Turning it on signs nobody out: each member without one sets it up at their next sign-in. Absent leaves it alone.",
+      "type": "boolean"
     }
   },
-  "required": [
-    "name"
-  ],
   "additionalProperties": false
 }

package/artifacts/schema/patch-org-response.schema.json

@@ -17,6 +17,10 @@
           "maxLength": 120,
           "description": "The organisation's display name. Free text, changed through `PATCH /api/org`."
         },
+        "require_two_factor": {
+          "type": "boolean",
+          "description": "Whether every member must have a second factor — a passkey or an authenticator app. A member without one sets it up at their next sign-in, before any session exists; nobody is signed out when it is switched on. It covers the console and the central MCP endpoint; server keys and robot bridges are not people and are not affected. Owners change it through `PATCH /api/org`."
+        },
         "created_at": {
           "type": "string",
           "format": "date-time",
@@ -27,6 +31,7 @@
       "required": [
         "id",
         "name",
+        "require_two_factor",
         "created_at"
       ],
       "additionalProperties": false,

package/artifacts/schema/put-app-auth-look-request.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "hosted_accent": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^#[0-9a-f]{6}$"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The accent colour of the hosted pages, `#rrggbb` in lowercase, or `null` for the neutral shell's own."
+    }
+  },
+  "required": [
+    "hosted_accent"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/put-app-auth-mcp-request.schema.json

@@ -5,23 +5,10 @@
     "mcp_enabled": {
       "type": "boolean",
       "description": "Whether this app serves an MCP endpoint at `/mcp/<identifier>`. Off refuses the whole OAuth surface for the app, not merely the tool calls, and is re-read on every request rather than cached off a token."
-    },
-    "mcp_login_url": {
-      "anyOf": [
-        {
-          "type": "string",
-          "maxLength": 500
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "The page an MCP authorization redirects to, with `{interaction}` where the interaction id goes. Not a token: the id names a pending request the server already holds, and the app authenticates the user itself before approving it."
     }
   },
   "required": [
-    "mcp_enabled",
-    "mcp_login_url"
+    "mcp_enabled"
   ],
   "additionalProperties": false
 }