@fleetless/contracts 5.3.0-next.1 → 6.0.0-next.2

package/artifacts/schema/accept-team-invite-request.schema.json

@@ -7,16 +7,22 @@
       "minLength": 1,
       "description": "The opaque invitation token from the link. Unknown, expired and already-accepted all collapse into `410 token_spent` — telling them apart would say whether a token ever existed."
     },
-    "password": {
-      "type": "string",
-      "minLength": 12,
-      "maxLength": 256,
-      "description": "The password the new Fleetless account will use. At least 12 characters."
+    "display_name": {
+      "description": "An optional name, overriding whatever the invitation pre-filled. Absent keeps it.",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        {
+          "type": "null"
+        }
+      ]
     }
   },
   "required": [
-    "token",
-    "password"
+    "token"
   ],
   "additionalProperties": false
 }

package/artifacts/schema/app-auth-config.schema.json

@@ -40,7 +40,7 @@
           "type": "null"
         }
       ],
-      "description": "The page in the developer's app that accepts an invitation, with `{token}` where the token goes. `null` when unconfigured, and then an invitation still issues but `send_mail` is refused with `409 target_state_conflict` — there would be nowhere for the link to point."
+      "description": "The page in the developer's app that accepts an invitation, with `{token}` where the token goes. `null` means the hosted page in `hosted_pages` is used."
     },
     "verify_url": {
       "anyOf": [
@@ -52,7 +52,7 @@
           "type": "null"
         }
       ],
-      "description": "The page that confirms a new address, with `{token}` where the token goes. Self-registration needs it: without a page to send people to, a registration would leave an account nobody can activate."
+      "description": "The page that confirms a new address, with `{token}` where the token goes. `null` means the hosted page in `hosted_pages` is used."
     },
     "reset_url": {
       "anyOf": [
@@ -64,7 +64,7 @@
           "type": "null"
         }
       ],
-      "description": "The page that takes a new password, with `{token}` where the token goes."
+      "description": "The page that takes a new password, with `{token}` where the token goes. `null` means the hosted page in `hosted_pages` is used."
     },
     "mcp_login_url": {
       "anyOf": [
@@ -76,7 +76,105 @@
           "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."
+      "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. `null` means the hosted MCP sign-in in `hosted_pages` is used."
+    },
+    "app_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500,
+          "format": "uri"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The app's own home page, linked as `Open <app>` when a hosted flow is done. `null` makes the hosted done page say `You can close this tab`."
+    },
+    "sign_in_methods": {
+      "type": "object",
+      "properties": {
+        "password": {
+          "type": "boolean",
+          "description": "Whether app users may sign in with a password. Off refuses `POST /api/client/login` with `method_not_allowed`, and registration and invitations then take no password."
+        },
+        "email_code": {
+          "type": "boolean",
+          "description": "Whether app users may sign in with a six-digit code mailed to them, valid ten minutes. A code needs no URL, so it works in local development and in an app with no web UI."
+        }
+      },
+      "required": [
+        "password",
+        "email_code"
+      ],
+      "additionalProperties": false,
+      "description": "Which sign-in methods the app offers: password, emailed code, or both — at least one. Identity providers stay on top of either. The default is password only."
+    },
+    "two_factor": {
+      "type": "string",
+      "enum": [
+        "off",
+        "optional",
+        "required"
+      ],
+      "description": "Whether the app asks for an authenticator code: `off` (the default), `optional` or `required`. A person with a confirmed authenticator is asked at every sign-in whatever the policy; a sign-in through an identity provider is never asked."
+    },
+    "hosted_logo_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "uri"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Where the hosted pages load the app's logo from, `<portal>/app/<identifier>/logo`, or `null` when no logo is stored. **Read-only** — the logo is written through `PUT /api/apps/:id/auth-config/logo`."
+    },
+    "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."
+    },
+    "hosted_pages": {
+      "type": "object",
+      "properties": {
+        "invite_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The hosted invitation page, `<portal>/app/<identifier>/invite/{token}`."
+        },
+        "verify_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The hosted email-confirmation page, `<portal>/app/<identifier>/verify/{token}`."
+        },
+        "reset_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The hosted new-password page, `<portal>/app/<identifier>/reset/{token}`."
+        },
+        "mcp_login_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The hosted MCP sign-in, `<portal>/app/<identifier>/mcp/{interaction}`."
+        }
+      },
+      "required": [
+        "invite_url",
+        "verify_url",
+        "reset_url",
+        "mcp_login_url"
+      ],
+      "additionalProperties": false,
+      "description": "The Fleetless-hosted pages an unset URL falls back to, as templates. **Read-only**: minted by the cloud from the auth portal and the app's identifier."
     },
     "oidc_callback_url": {
       "type": "string",
@@ -99,6 +197,12 @@
     "verify_url",
     "reset_url",
     "mcp_login_url",
+    "app_url",
+    "sign_in_methods",
+    "two_factor",
+    "hosted_logo_url",
+    "hosted_accent",
+    "hosted_pages",
     "oidc_callback_url",
     "updated_at"
   ],

package/artifacts/schema/app-hosted-pages.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "invite_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "The hosted invitation page, `<portal>/app/<identifier>/invite/{token}`."
+    },
+    "verify_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "The hosted email-confirmation page, `<portal>/app/<identifier>/verify/{token}`."
+    },
+    "reset_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "The hosted new-password page, `<portal>/app/<identifier>/reset/{token}`."
+    },
+    "mcp_login_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "The hosted MCP sign-in, `<portal>/app/<identifier>/mcp/{interaction}`."
+    }
+  },
+  "required": [
+    "invite_url",
+    "verify_url",
+    "reset_url",
+    "mcp_login_url"
+  ],
+  "additionalProperties": false
+}

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

@@ -33,17 +33,10 @@
       "description": "When the token stops working. Seven days from issue; an expired token answers exactly as an unknown one does."
     },
     "accept_url": {
-      "anyOf": [
-        {
-          "type": "string",
-          "maxLength": 500,
-          "format": "uri"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "The link to give the invitee, built from the app's `invite_url` with the token substituted for `{token}`. **`null` when the app has configured no `invite_url`** — there is nowhere for the link to point, and Fleetless serves no page of its own for an app user. Bounded like every other URL that gets mailed, logged and rendered."
+      "type": "string",
+      "maxLength": 500,
+      "format": "uri",
+      "description": "The link to give the invitee: the app's `invite_url` with the token substituted for `{token}`, or the Fleetless-hosted invitation page when the app has configured none. Bounded like every other URL that gets mailed, logged and rendered."
     },
     "mail": {
       "type": "string",
@@ -53,7 +46,7 @@
         "not_configured",
         "failed"
       ],
-      "description": "What happened to the mail: `sent` means the SMTP server accepted it, not that it was delivered; `not_requested` means none was attempted — the caller asked for none, or the app has no `invite_url` for a link to point at; `not_configured` is an expected state and not a failure; `failed` is the one worth somebody's attention."
+      "description": "What happened to the mail: `sent` means the SMTP server accepted it, not that it was delivered; `not_requested` means none was attempted because the caller asked for none; `not_configured` is an expected state and not a failure; `failed` is the one worth somebody's attention."
     }
   },
   "required": [

package/artifacts/schema/app-mail-template-list-response.schema.json

@@ -3,7 +3,7 @@
   "type": "object",
   "properties": {
     "templates": {
-      "maxItems": 3,
+      "maxItems": 4,
       "type": "array",
       "items": {
         "type": "object",
@@ -13,9 +13,10 @@
             "enum": [
               "invite",
               "verify",
-              "reset"
+              "reset",
+              "login_code"
             ],
-            "description": "Which of the three mails this template replaces."
+            "description": "Which of the four mails this template replaces."
           },
           "subject": {
             "type": "string",

package/artifacts/schema/app-mail-template.schema.json

@@ -7,9 +7,10 @@
       "enum": [
         "invite",
         "verify",
-        "reset"
+        "reset",
+        "login_code"
       ],
-      "description": "Which of the three mails this template replaces."
+      "description": "Which of the four mails this template replaces."
     },
     "subject": {
       "type": "string",

package/artifacts/schema/app-sign-in-methods.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "password": {
+      "type": "boolean",
+      "description": "Whether app users may sign in with a password. Off refuses `POST /api/client/login` with `method_not_allowed`, and registration and invitations then take no password."
+    },
+    "email_code": {
+      "type": "boolean",
+      "description": "Whether app users may sign in with a six-digit code mailed to them, valid ten minutes. A code needs no URL, so it works in local development and in an app with no web UI."
+    }
+  },
+  "required": [
+    "password",
+    "email_code"
+  ],
+  "additionalProperties": false
+}

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

@@ -80,6 +80,41 @@
             ],
             "description": "When this user last signed in, or `null` if they never have. Required and nullable rather than optional, so *never logged in* stays distinguishable from *this field was not loaded*."
           },
+          "two_factor": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Whether the account has a confirmed authenticator app (TOTP). When it has, every sign-in that yields a session asks for a code as well — whatever the app's policy — except a sign-in through an identity provider, which owns that sign-in."
+              },
+              "enabled_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 the authenticator was confirmed, or `null` while `enabled` is `false`."
+              },
+              "recovery_codes_left": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 10,
+                "description": "How many of the ten single-use recovery codes are still unspent. `0` while `enabled` is `false`."
+              }
+            },
+            "required": [
+              "enabled",
+              "enabled_at",
+              "recovery_codes_left"
+            ],
+            "additionalProperties": false,
+            "description": "The account's second factor, as a developer's user list shows it. No secret and no code travels here; resetting it is `DELETE /api/apps/:id/users/:userId/two-factor`."
+          },
           "created_at": {
             "type": "string",
             "format": "date-time",
@@ -97,6 +132,7 @@
           "has_password",
           "providers",
           "last_login_at",
+          "two_factor",
           "created_at"
         ],
         "additionalProperties": false

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

@@ -75,6 +75,41 @@
       ],
       "description": "When this user last signed in, or `null` if they never have. Required and nullable rather than optional, so *never logged in* stays distinguishable from *this field was not loaded*."
     },
+    "two_factor": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether the account has a confirmed authenticator app (TOTP). When it has, every sign-in that yields a session asks for a code as well — whatever the app's policy — except a sign-in through an identity provider, which owns that sign-in."
+        },
+        "enabled_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 the authenticator was confirmed, or `null` while `enabled` is `false`."
+        },
+        "recovery_codes_left": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "description": "How many of the ten single-use recovery codes are still unspent. `0` while `enabled` is `false`."
+        }
+      },
+      "required": [
+        "enabled",
+        "enabled_at",
+        "recovery_codes_left"
+      ],
+      "additionalProperties": false,
+      "description": "The account's second factor, as a developer's user list shows it. No secret and no code travels here; resetting it is `DELETE /api/apps/:id/users/:userId/two-factor`."
+    },
     "created_at": {
       "type": "string",
       "format": "date-time",
@@ -92,6 +127,7 @@
     "has_password",
     "providers",
     "last_login_at",
+    "two_factor",
     "created_at"
   ],
   "additionalProperties": false

package/artifacts/schema/audit-query.schema.json

@@ -48,12 +48,6 @@
       "minLength": 1,
       "maxLength": 40
     },
-    "target_id": {
-      "description": "Events whose target is this id; for a robot also the events that name it in `details.robot_id` (`action.invoked`, `service.called`, …), so a robot's events include what was started on it.",
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 200
-    },
     "from_ms": {
       "anyOf": [
         {

package/artifacts/schema/auth-me-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
@@ -73,6 +78,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",
@@ -86,6 +112,7 @@
         "email",
         "display_name",
         "tier",
+        "two_factor",
         "created_at"
       ],
       "additionalProperties": false

package/artifacts/schema/auth-ok.schema.json

@@ -95,6 +95,17 @@
             }
           ],
           "description": "The address of the Fleetless user or app user behind this session, and `null` for a server key, which is not a person."
+        },
+        "two_factor_enabled": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Whether the app user has a confirmed authenticator, so the app's account settings can offer to turn it on or off. `null` unless `kind` is `app_user`."
         }
       },
       "required": [
@@ -104,7 +115,8 @@
         "server_key_id",
         "app_id",
         "role_id",
-        "email"
+        "email",
+        "two_factor_enabled"
       ]
     }
   },

package/artifacts/schema/client-accept-invitation-request.schema.json

@@ -8,10 +8,10 @@
       "description": "The opaque token from the invitation link, valid seven days. Unknown, expired, revoked and already-accepted all answer `410 token_spent`."
     },
     "password": {
+      "description": "The password the new account will use, at least 12 characters. **Required while the app's password method is on, refused while it is off** — both as `400 validation_error` naming `password`. An email-code-only app accepts invitations without one.",
       "type": "string",
       "minLength": 12,
-      "maxLength": 256,
-      "description": "The password the new account will use."
+      "maxLength": 256
     },
     "display_name": {
       "description": "An optional name, overriding whatever the invitation pre-filled.",
@@ -28,8 +28,7 @@
     }
   },
   "required": [
-    "token",
-    "password"
+    "token"
   ],
   "additionalProperties": false
 }

package/artifacts/schema/client-identity.schema.json

@@ -88,6 +88,17 @@
         }
       ],
       "description": "The address of the Fleetless user or app user behind this session, and `null` for a server key, which is not a person."
+    },
+    "two_factor_enabled": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Whether the app user has a confirmed authenticator, so the app's account settings can offer to turn it on or off. `null` unless `kind` is `app_user`."
     }
   },
   "required": [
@@ -97,7 +108,8 @@
     "server_key_id",
     "app_id",
     "role_id",
-    "email"
+    "email",
+    "two_factor_enabled"
   ],
   "additionalProperties": false
 }

package/artifacts/schema/client-login-code-request.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "app_identifier": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 63,
+      "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
+      "description": "The app to sign in to. An identifier no app carries is `404 not_found`; the address is never the subject of a refusal."
+    },
+    "email": {
+      "type": "string",
+      "format": "email",
+      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+      "description": "The address to mail the code to, trimmed and compared case-insensitively. `202` whether or not it names an account of this app."
+    }
+  },
+  "required": [
+    "app_identifier",
+    "email"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/client-login-code-verify-request.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "app_identifier": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 63,
+      "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
+      "description": "The app the code was requested for."
+    },
+    "email": {
+      "type": "string",
+      "format": "email",
+      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+      "description": "The address the code was mailed to, as typed when it was requested; trimmed and compared case-insensitively."
+    },
+    "code": {
+      "type": "string",
+      "pattern": "^\\d{6}$",
+      "description": "The six digits from the mail, exactly — leading zeros included, no spaces."
+    }
+  },
+  "required": [
+    "app_identifier",
+    "email",
+    "code"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/client-provider-list-response.schema.json

@@ -24,11 +24,31 @@
         ],
         "additionalProperties": false
       },
-      "description": "The app's **enabled** providers, slug and display name only. An app with none answers an empty array, which is the state of an app that offers password login alone."
+      "description": "The app's **enabled** providers, slug and display name only. An app with none answers an empty array, which is the state of an app that offers password or code sign-in alone."
+    },
+    "sign_in_methods": {
+      "type": "object",
+      "properties": {
+        "password": {
+          "type": "boolean",
+          "description": "Whether app users may sign in with a password. Off refuses `POST /api/client/login` with `method_not_allowed`, and registration and invitations then take no password."
+        },
+        "email_code": {
+          "type": "boolean",
+          "description": "Whether app users may sign in with a six-digit code mailed to them, valid ten minutes. A code needs no URL, so it works in local development and in an app with no web UI."
+        }
+      },
+      "required": [
+        "password",
+        "email_code"
+      ],
+      "additionalProperties": false,
+      "description": "Which of password and emailed code the app accepts, so its sign-in page draws the right fields without guessing. The same value the developer set; public, like the provider buttons."
     }
   },
   "required": [
-    "providers"
+    "providers",
+    "sign_in_methods"
   ],
   "additionalProperties": false
 }