@fleetless/contracts 5.3.0-next.1 → 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/job-actor.schema.json

@@ -23,26 +23,12 @@
       "minLength": 1,
       "maxLength": 200,
       "description": "A display name taken at invoke time — the email for a Fleetless user or an app user, the key's own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history."
-    },
-    "name": {
-      "anyOf": [
-        {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 200
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "The person's display name when the job started: the Fleetless user's `display_name` for a developer, the app user's `display_name` for an app user. `null` for a server key, when the person had no name set, and for runs recorded before contracts 5.3.0. Show `label` when it is null."
     }
   },
   "required": [
     "kind",
     "id",
-    "label",
-    "name"
+    "label"
   ],
   "additionalProperties": false
 }

package/artifacts/schema/job-run-list-response.schema.json

@@ -142,26 +142,12 @@
                 "minLength": 1,
                 "maxLength": 200,
                 "description": "A display name taken at invoke time — the email for a Fleetless user or an app user, the key's own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history."
-              },
-              "name": {
-                "anyOf": [
-                  {
-                    "type": "string",
-                    "minLength": 1,
-                    "maxLength": 200
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "description": "The person's display name when the job started: the Fleetless user's `display_name` for a developer, the app user's `display_name` for an app user. `null` for a server key, when the person had no name set, and for runs recorded before contracts 5.3.0. Show `label` when it is null."
               }
             },
             "required": [
               "kind",
               "id",
-              "label",
-              "name"
+              "label"
             ],
             "additionalProperties": false,
             "description": "Who invoked the run, and what they were acting as at the time."

package/artifacts/schema/job-run.schema.json

@@ -137,26 +137,12 @@
           "minLength": 1,
           "maxLength": 200,
           "description": "A display name taken at invoke time — the email for a Fleetless user or an app user, the key's own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history."
-        },
-        "name": {
-          "anyOf": [
-            {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 200
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "description": "The person's display name when the job started: the Fleetless user's `display_name` for a developer, the app user's `display_name` for an app user. `null` for a server key, when the person had no name set, and for runs recorded before contracts 5.3.0. Show `label` when it is null."
         }
       },
       "required": [
         "kind",
         "id",
-        "label",
-        "name"
+        "label"
       ],
       "additionalProperties": false,
       "description": "Who invoked the run, and what they were acting as at the time."

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