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

package/CHANGELOG.md

@@ -90,6 +90,18 @@ version.
   `acceptTeamInviteRequest` takes an optional `display_name` and no
   password. The default invitation mail no longer asks the invitee to
   choose a password.
+- **`appInvitation.accept_url` is never `null`**: an app with no
+  `invite_url` gets the hosted invitation page's link.
+- **`appMailTemplateListResponse.templates` holds up to four** (was three),
+  with `login_code`.
+- **The portal's identify step mails a sign-in code** (`POST
+  /console/oauth/identify`, `POST /mcp/oauth/identify`) instead of handing
+  back a password step, and answers the same for every address.
+- **A password reset and a password change are refused with `403
+  method_not_allowed`** while the app has the password method off — `POST
+  /api/client/password/reset`, `…/password/reset/confirm`,
+  `…/password/change` and the developer's `POST
+  /api/apps/:id/users/:userId/reset-password`.
 
 ### Removed
 
@@ -102,11 +114,11 @@ version.
   /console/oauth/login` and `POST /mcp/oauth/login`. Fleetless users sign
   in by emailed code or passkey; the portal sign-up is the one way to
   create an organisation. `passwordChangeRequest` stays, for `POST
-  /api/client/password/change`. Together with the newly required fields
-  above (`appUser.two_factor`, `org.require_two_factor`,
+  /api/client/password/change`. The newly required fields above
+  (`appUser.two_factor`, `org.require_two_factor`,
   `fleetlessUser.two_factor`, `clientIdentity.two_factor_enabled`,
   `clientProviderListResponse.sign_in_methods`) and the narrowed `mcp`
-  slice, this is why the release is a major.
+  slice break existing readers as well.
 
 ## [5.2.0] — 2026-09-30
 

package/artifacts/openapi.json

@@ -2011,7 +2011,7 @@
             }
           },
           "default": {
-            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `target_state_conflict`.",
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `target_state_conflict`, `method_not_allowed`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -2021,7 +2021,7 @@
             }
           }
         },
-        "description": "The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
+        "description": "The support door beside `POST /api/client/password/reset`, refused like it with `403 method_not_allowed` while the app has the password method off: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
       }
     },
     "/api/apps/{id}/users/{userId}/two-factor": {
@@ -3181,7 +3181,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3236,7 +3236,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3301,7 +3301,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3351,7 +3351,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3418,7 +3418,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -4767,7 +4767,7 @@
             }
           }
         },
-        "description": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out only for an account that may sign in. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly.",
+        "description": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out for an `active` account and for one still `pending_verification` — spending the code proves the address, as the verification link would — and never for a `blocked` one or an unknown address. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly.",
         "requestBody": {
           "required": true,
           "content": {
@@ -4956,7 +4956,7 @@
             "description": "Success."
           },
           "default": {
-            "description": "An error envelope. Codes this route is known to answer: `rate_limited`, `validation_error`, `not_found`.",
+            "description": "An error envelope. Codes this route is known to answer: `rate_limited`, `validation_error`, `not_found`, `method_not_allowed`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4966,7 +4966,7 @@
             }
           }
         },
-        "description": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none.",
+        "description": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. `403 method_not_allowed` when the app has the password method off — a reset link whose confirmation would be refused is not mailed; the code names the app's policy, not a person. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none.",
         "requestBody": {
           "required": true,
           "content": {
@@ -5179,7 +5179,7 @@
             }
           },
           "default": {
-            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `validation_error`, `invalid_credentials`, `target_state_conflict`.",
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `validation_error`, `invalid_credentials`, `target_state_conflict`, `method_not_allowed`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5189,7 +5189,7 @@
             }
           }
         },
-        "description": "The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here.",
+        "description": "`403 method_not_allowed` when the app has the password method off: a stored password stays stored but is not in use, so it is not changed either. The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here.",
         "requestBody": {
           "required": true,
           "content": {
@@ -5326,9 +5326,9 @@
             }
           }
         },
-        "description": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed.",
+        "description": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge and an empty or missing body. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed.",
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
@@ -9853,17 +9853,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: 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. Nullable for readers of the earlier shape; the cloud always fills it."
+            "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",

package/artifacts/routes.json

@@ -1114,10 +1114,11 @@
         "token_revoked",
         "invalid_uuid",
         "not_found",
-        "target_state_conflict"
+        "target_state_conflict",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
+      "notes": "The support door beside `POST /api/client/password/reset`, refused like it with `403 method_not_allowed` while the app has the password method off: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
     },
     {
       "method": "DELETE",
@@ -1800,7 +1801,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1834,7 +1835,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1870,7 +1871,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1904,7 +1905,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -1940,7 +1941,7 @@
         },
         {
           "name": "kind",
-          "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`."
+          "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`."
         }
       ],
       "query": null,
@@ -2406,7 +2407,7 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a client whose dynamic registration lapsed in between."
+      "notes": "HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a client whose dynamic registration lapsed in between. It offers the email field and `Sign in with a passkey`, and opening it binds the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks."
     },
     {
       "method": "POST",
@@ -2425,10 +2426,11 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "token_spent"
+        "token_spent",
+        "wrong_browser"
       ],
       "transport": "http",
-      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/mcp/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
+      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/mcp/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
     },
     {
       "method": "POST",
@@ -2544,7 +2546,7 @@
         "wrong_browser"
       ],
       "transport": "http",
-      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use."
+      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST /mcp/oauth/passkey` can require it."
     },
     {
       "method": "POST",
@@ -2808,7 +2810,7 @@
       "response": null,
       "errors": [],
       "transport": "http",
-      "notes": "HTML: the email field, `Email me a code`, and `Sign in with a passkey`. An expired, consumed, unknown or hand-edited interaction renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The page resolves nothing about the address typed into it, so there is no enumeration oracle here at all."
+      "notes": "HTML: the email field, `Email me a code`, and `Sign in with a passkey`. Opening it binds the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks. An expired, consumed, unknown or hand-edited interaction renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The page resolves nothing about the address typed into it, so there is no enumeration oracle here at all."
     },
     {
       "method": "POST",
@@ -2827,10 +2829,11 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "token_spent"
+        "token_spent",
+        "wrong_browser"
       ],
       "transport": "http",
-      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/console/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
+      "notes": "The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets `{ \"next\": \"/console/oauth/code\" }`, which has no schema. A dead interaction is `410 token_spent`."
     },
     {
       "method": "POST",
@@ -2946,7 +2949,7 @@
         "wrong_browser"
       ],
       "transport": "http",
-      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use."
+      "notes": "Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` (`Sign in with a passkey`); after the code step they name the account's own passkeys. User verification is required. The challenge is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST /console/oauth/passkey` can require it."
     },
     {
       "method": "POST",
@@ -4004,7 +4007,7 @@
         "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out only for an account that may sign in. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly."
+      "notes": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out for an `active` account and for one still `pending_verification` — spending the code proves the address, as the verification link would — and never for a `blocked` one or an unknown address. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly."
     },
     {
       "method": "POST",
@@ -4117,10 +4120,11 @@
       "errors": [
         "rate_limited",
         "validation_error",
-        "not_found"
+        "not_found",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none."
+      "notes": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. `403 method_not_allowed` when the app has the password method off — a reset link whose confirmation would be refused is not mailed; the code names the app's policy, not a person. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none."
     },
     {
       "method": "POST",
@@ -4235,10 +4239,11 @@
         "forbidden",
         "validation_error",
         "invalid_credentials",
-        "target_state_conflict"
+        "target_state_conflict",
+        "method_not_allowed"
       ],
       "transport": "http",
-      "notes": "The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here."
+      "notes": "`403 method_not_allowed` when the app has the password method off: a stored password stays stored but is not in use, so it is not changed either. The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here."
     },
     {
       "method": "GET",
@@ -4299,6 +4304,7 @@
       "params": [],
       "query": null,
       "request": "client-two-factor-setup-request",
+      "requestOptional": true,
       "response": "two-factor-setup-response",
       "errors": [
         "rate_limited",
@@ -4308,7 +4314,7 @@
         "target_state_conflict"
       ],
       "transport": "http",
-      "notes": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed."
+      "notes": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge and an empty or missing body. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed."
     },
     {
       "method": "POST",

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: 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. Nullable for readers of the earlier shape; the cloud always fills it."
+      "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",

package/dist/app-users.d.ts

@@ -177,9 +177,8 @@ export type CreateAppInvitationRequest = z.infer<typeof createAppInvitationReque
  *
  * The link points into the developer's app, at their configured `invite_url`,
  * or at the Fleetless-hosted invitation page (`appAuthConfig.hosted_pages`)
- * when the app has configured none. **`accept_url` stays nullable** so a
- * reader written against the earlier shape keeps parsing; the cloud fills it
- * in every case now that a hosted page always exists.
+ * when the app has configured none — so there is always a link, and
+ * `accept_url` is never `null`.
  */
 export declare const appInvitation: z.ZodObject<{
     id: z.ZodUUID;
@@ -187,7 +186,7 @@ export declare const appInvitation: z.ZodObject<{
     email: z.ZodEmail;
     role_id: z.ZodUUID;
     expires_at: z.ZodISODateTime;
-    accept_url: z.ZodNullable<z.ZodURL>;
+    accept_url: z.ZodURL;
     mail: z.ZodEnum<{
         sent: "sent";
         not_requested: "not_requested";

package/dist/app-users.js

@@ -210,9 +210,8 @@ export const createAppInvitationRequest = z
  *
  * The link points into the developer's app, at their configured `invite_url`,
  * or at the Fleetless-hosted invitation page (`appAuthConfig.hosted_pages`)
- * when the app has configured none. **`accept_url` stays nullable** so a
- * reader written against the earlier shape keeps parsing; the cloud fills it
- * in every case now that a hosted page always exists.
+ * when the app has configured none — so there is always a link, and
+ * `accept_url` is never `null`.
  */
 export const appInvitation = z.object({
     id: z.uuid().meta({ description: 'The invitation, as listed and revoked by the developer.' }),
@@ -220,8 +219,8 @@ export const appInvitation = z.object({
     email: z.email().meta({ description: 'The address the invitation was addressed to.' }),
     role_id: z.uuid().meta({ description: 'The role the invitee holds once they accept. Resolved at creation, so a later change to the app\'s default role does not silently re-aim an outstanding invitation.' }),
     expires_at: z.iso.datetime().meta({ description: 'When the token stops working. Seven days from issue; an expired token answers exactly as an unknown one does.' }),
-    accept_url: z.url().max(500).nullable().meta({
-        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. Nullable for readers of the earlier shape; the cloud always fills it.',
+    accept_url: z.url().max(500).meta({
+        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: mailStatus.meta({
         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.',

package/dist/errors.js

@@ -589,10 +589,9 @@ export const ERROR_CODES = [
      * string on the validation envelope is not a code a consumer can switch on.
      *
      * Its producers in the two-space model are the ones about an app or an
-     * account rather than about a caller: `send_mail: true` on an app that has
-     * configured no `invite_url` (the `details` name the field), and a password
-     * change on an app user who has no password at all — an OIDC-only account,
-     * where the session is live and it is the target's state that refuses.
+     * account rather than about a caller — for example a password change on an
+     * app user who has no password at all, an OIDC-only account, where the
+     * session is live and it is the target's state that refuses.
      *
      * **A tier change aimed at somebody who is not a Fleetless user of this org
      * was listed here and stopped being a producer at the cut.** That refusal
@@ -857,10 +856,10 @@ export const ERROR_CODES = [
      */
     'invalid_code',
     /**
-     * `403`: the app does not offer this sign-in method — a password login on a
-     * code-only app, a code request on a password-only one, or a password where
-     * the app takes none. It names the app's policy, never a person, so it is
-     * no enumeration oracle.
+     * `403`: the app does not offer this sign-in method — a password login, a
+     * password reset or a password change on a code-only app, or a code request
+     * on a password-only one. It names the app's policy, never a person, so it
+     * is no enumeration oracle.
      */
     'method_not_allowed',
 ];

package/dist/identity.d.ts

@@ -220,11 +220,9 @@ export type WaitlistRequest = z.infer<typeof waitlistRequest>;
  *                      no sender can promise that, and this value must never
  *                      be rendered as if it could.
  * - `not_requested`  — no mail was attempted: the caller asked for none
- *                      (`send_mail: false`), or there was no link for one to
- *                      carry (the app has configured no `invite_url`, which
- *                      the `null` `accept_url` beside it says). **A fourth
- *                      word rather than a reuse of `not_configured`**: the
- *                      deployment's mailer is irrelevant in both cases, and a
+ *                      (`send_mail: false`). **A fourth word rather than a
+ *                      reuse of `not_configured`**: the deployment's mailer
+ *                      is irrelevant there, and a
  *                      console reading "mail server not configured" beside an
  *                      invitation whose mail checkbox was off would send a
  *                      developer to fix something that is not broken.

package/dist/identity.js

@@ -225,11 +225,9 @@ export const waitlistRequest = z.object({ email: z.email().max(254) });
  *                      no sender can promise that, and this value must never
  *                      be rendered as if it could.
  * - `not_requested`  — no mail was attempted: the caller asked for none
- *                      (`send_mail: false`), or there was no link for one to
- *                      carry (the app has configured no `invite_url`, which
- *                      the `null` `accept_url` beside it says). **A fourth
- *                      word rather than a reuse of `not_configured`**: the
- *                      deployment's mailer is irrelevant in both cases, and a
+ *                      (`send_mail: false`). **A fourth word rather than a
+ *                      reuse of `not_configured`**: the deployment's mailer
+ *                      is irrelevant there, and a
  *                      console reading "mail server not configured" beside an
  *                      invitation whose mail checkbox was off would send a
  *                      developer to fix something that is not broken.

package/dist/routes.d.ts

@@ -103,9 +103,16 @@ export declare const IN_HANDLER_ROUTES: readonly string[];
  *
  * Every step is a page the auth portal serves to itself: `audience:
  * 'internal'`, no request schema — the handlers read form fields by hand — and
- * HTML for a browser form post, JSON for a JSON caller. Every step after
- * `identify` needs the browser-proof cookie set there, so a step posted from
- * another browser renders the `wrong_browser` page. The interaction's ten
+ * HTML for a browser form post, JSON for a JSON caller.
+ *
+ * **The browser-proof cookie binds the interaction to one browser**, and it
+ * is set by whichever of these comes first for the interaction: the email
+ * card (`GET <prefix>/interaction/:id`), `POST <prefix>/identify`, or `POST
+ * <prefix>/passkey/options`. The email card is what a browser normally opens
+ * first; the two steps set it for a caller that never loaded the page, so
+ * `Sign in with a passkey` works without an email step. Once the interaction
+ * is bound, every step — those three included — without the matching cookie
+ * renders the `wrong_browser` page. The interaction's ten
  * minutes cover every step; only when the last one is done is anything
  * minted. **For `/mcp/oauth`, "done" means the consent step**, as the
  * password did before.

package/dist/routes.js

@@ -126,9 +126,16 @@ const CLIENT_GUARD = ['unauthorized', 'token_expired', 'token_revoked', 'forbidd
  *
  * Every step is a page the auth portal serves to itself: `audience:
  * 'internal'`, no request schema — the handlers read form fields by hand — and
- * HTML for a browser form post, JSON for a JSON caller. Every step after
- * `identify` needs the browser-proof cookie set there, so a step posted from
- * another browser renders the `wrong_browser` page. The interaction's ten
+ * HTML for a browser form post, JSON for a JSON caller.
+ *
+ * **The browser-proof cookie binds the interaction to one browser**, and it
+ * is set by whichever of these comes first for the interaction: the email
+ * card (`GET <prefix>/interaction/:id`), `POST <prefix>/identify`, or `POST
+ * <prefix>/passkey/options`. The email card is what a browser normally opens
+ * first; the two steps set it for a caller that never loaded the page, so
+ * `Sign in with a passkey` works without an email step. Once the interaction
+ * is bound, every step — those three included — without the matching cookie
+ * renders the `wrong_browser` page. The interaction's ten
  * minutes cover every step; only when the last one is done is anything
  * minted. **For `/mcp/oauth`, "done" means the consent step**, as the
  * password did before.
@@ -150,11 +157,11 @@ export function developerSignInRoutes(prefix) {
         params: [], query: null, request: null, response, errors: ['rate_limited', ...errors], transport: 'http', notes,
     });
     return [
-        step('/identify', 'Takes the email address, mails a sign-in code and hands back the code step.', null, ['validation_error', 'token_spent'], 'The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten ' +
+        step('/identify', 'Takes the email address, mails a sign-in code and hands back the code step.', null, ['validation_error', 'token_spent', 'wrong_browser'], 'The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten ' +
             'minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up ' +
             'is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request ' +
             'within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is ' +
-            `set here. A browser form post gets the code card; a JSON caller gets \`{ "next": "${prefix}/code" }\`, which has no schema. A dead ` +
+            `set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets \`{ "next": "${prefix}/code" }\`, which has no schema. A dead ` +
             'interaction is `410 token_spent`.'),
         step('/code', 'Checks the emailed code and finishes the sign-in, or hands back the second step.', oauthRedirectResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_code'], 'A wrong code renders the code card again with the attempts left (`400 invalid_code`, `details.attempts_left`); a code spent, past ' +
             'its ten minutes or out of its five attempts is `410 token_spent` and a new one has to be asked for. Spaces inside a typed code are ' +
@@ -171,7 +178,9 @@ export function developerSignInRoutes(prefix) {
             `a \`303\` to ${done}; a JSON caller that URL as \`redirect_to\`.`),
         step('/passkey/options', 'Answers the WebAuthn request options for a passkey sign-in or second step.', webauthnOptionsResponse, ['token_spent', 'wrong_browser'], 'Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` ' +
             '(`Sign in with a passkey`); after the code step they name the account\'s own passkeys. User verification is required. The challenge ' +
-            'is bound to the interaction and single-use.'),
+            'is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the ' +
+            'browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST ' + prefix + '/passkey` ' +
+            'can require it.'),
         step('/passkey', 'Checks a passkey assertion; a passkey completes the sign-in on its own.', oauthRedirectResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_credentials'], '**A passkey is a full sign-in**: it proves possession and user verification, two factors, so it skips the emailed code and the ' +
             'second step — used as the second step, it finishes it. An assertion that does not verify, or names no passkey of an account, is ' +
             '`401 invalid_credentials`, the same answer for both. When the organisation requires two-factor, a passkey satisfies it. A browser ' +
@@ -696,8 +705,9 @@ export const ROUTES = [
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 202,
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'userId', description: 'The app user\'s uuid, from `GET /api/apps/:id/users`; a user of another app answers `404`.' }],
         query: null, request: null, response: mailOutcome,
-        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'target_state_conflict'], transport: 'http',
-        notes: 'The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a ' +
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'target_state_conflict', 'method_not_allowed'], transport: 'http',
+        notes: 'The support door beside `POST /api/client/password/reset`, refused like it with `403 method_not_allowed` while the app has the ' +
+            'password method off: the same one-hour token and the same link, triggered by a developer for a ' +
             'user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read ' +
             'the user list — so this one answers what actually happened: `{ "mail": mailStatus }`, where `not_configured` is a deployment without a ' +
             'mailer and `failed` is the state worth somebody\'s attention. The link points at the app\'s `reset_url`, or at the hosted reset page ' +
@@ -1018,7 +1028,7 @@ export const ROUTES = [
         method: 'GET', path: '/api/apps/:id/mail-templates/:kind', section: 'apps',
         summary: 'Reads one custom mail template of the app.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: null, response: appMailTemplate,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
         notes: 'The `kind` segment is a `mailTemplateKind`, so a fourth word is `400 validation_error` — the path names a set that is closed, and ' +
@@ -1030,7 +1040,7 @@ export const ROUTES = [
         method: 'PUT', path: '/api/apps/:id/mail-templates/:kind', section: 'apps',
         summary: 'Stores or replaces the app\'s template for one kind of mail, refusing one that does not render.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: putAppMailTemplateRequest, response: appMailTemplate,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found', 'template_invalid', 'rate_limited'], transport: 'http',
         notes: 'The body carries `subject`, `text` and an optional `html`, each a Liquid template; `kind` is in the path and `updated_at` is the ' +
@@ -1048,7 +1058,7 @@ export const ROUTES = [
         method: 'DELETE', path: '/api/apps/:id/mail-templates/:kind', section: 'apps',
         summary: 'Drops the app\'s custom template for one kind, returning that mail to the Fleetless default.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 204,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: null, response: null,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
         notes: 'The mail keeps being sent — this removes the developer\'s wording, not the message. A kind that already has no custom template answers ' +
@@ -1059,7 +1069,7 @@ export const ROUTES = [
         method: 'POST', path: '/api/apps/:id/mail-templates/:kind/preview', section: 'apps',
         summary: 'Renders a template with sample data and answers the three parts, storing nothing.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: mailTemplatePreviewRequest, response: mailTemplatePreviewResponse,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found', 'template_invalid', 'rate_limited'], transport: 'http',
         notes: 'Takes the same document the PUT does and writes nothing, so a developer can see the rendered subject, text and HTML before anybody ' +
@@ -1076,7 +1086,7 @@ export const ROUTES = [
         method: 'POST', path: '/api/apps/:id/mail-templates/:kind/test', section: 'apps',
         summary: 'Sends the rendered template as a real mail to the calling developer.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 202,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: mailTemplatePreviewRequest, response: mailOutcome,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found', 'template_invalid', 'rate_limited', 'target_state_conflict'],
         transport: 'http',
@@ -1296,7 +1306,8 @@ export const ROUTES = [
         query: null, request: null, response: null, errors: [], transport: 'http',
         notes: 'HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which ' +
             'the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a ' +
-            'client whose dynamic registration lapsed in between.',
+            'client whose dynamic registration lapsed in between. It offers the email field and `Sign in with a passkey`, and opening it binds ' +
+            'the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks.',
     },
     ...developerSignInRoutes('/mcp/oauth'),
     {
@@ -1347,7 +1358,8 @@ export const ROUTES = [
         audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'id', description: 'The interaction id minted by `GET /console/oauth/authorize`, which redirects the browser here.' }],
         query: null, request: null, response: null, errors: [], transport: 'http',
-        notes: 'HTML: the email field, `Email me a code`, and `Sign in with a passkey`. An expired, consumed, unknown or hand-edited interaction ' +
+        notes: 'HTML: the email field, `Email me a code`, and `Sign in with a passkey`. Opening it binds the interaction to this browser with the ' +
+            'browser-proof cookie, which every sign-in step after it checks. An expired, consumed, unknown or hand-edited interaction ' +
             'renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The ' +
             'page resolves nothing about the address typed into it, so there is no enumeration oracle here at all.',
     },
@@ -1613,7 +1625,8 @@ export const ROUTES = [
         errors: ['rate_limited', 'validation_error', 'not_found', 'method_not_allowed'], transport: 'http',
         notes: '**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an ' +
             'active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out ' +
-            'only for an account that may sign in. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires ' +
+            'for an `active` account and for one still `pending_verification` — spending the code proves the address, as the verification link ' +
+            'would — and never for a `blocked` one or an unknown address. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires ' +
             'the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and ' +
             'compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has ' +
             'the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly.',
@@ -1697,8 +1710,10 @@ export const ROUTES = [
         summary: 'Mails an app user a reset link, and answers the same either way.',
         audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 202,
         params: [], query: null, request: clientPasswordResetRequest, response: null,
-        errors: ['rate_limited', 'validation_error', 'not_found'], transport: 'http',
+        errors: ['rate_limited', 'validation_error', 'not_found', 'method_not_allowed'], transport: 'http',
         notes: 'The pair of app identifier and address is the identifier: an app user\'s address is unique only within their app. ' +
+            '`403 method_not_allowed` when the app has the password method off — a reset link whose confirmation would be refused is not mailed; ' +
+            'the code names the app\'s policy, not a person. ' +
             'Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an ' +
             'identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link ' +
             'points at the app\'s `reset_url`, or at the hosted reset page when the app has configured none.',
@@ -1773,8 +1788,10 @@ export const ROUTES = [
         summary: "Changes an app user's own password and answers a fresh session.",
         audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 200,
         params: [], query: null, request: passwordChangeRequest, response: sessionTokens,
-        errors: [...CLIENT_GUARD, 'validation_error', 'invalid_credentials', 'target_state_conflict'], transport: 'http',
-        notes: 'The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key ' +
+        errors: [...CLIENT_GUARD, 'validation_error', 'invalid_credentials', 'target_state_conflict', 'method_not_allowed'], transport: 'http',
+        notes: '`403 method_not_allowed` when the app has the password method off: a stored password stays stored but is not in use, so it is not ' +
+            'changed either. ' +
+            'The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key ' +
             'reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made ' +
             'the change stays signed in. An app user belongs to one app, so "every session" is this app\'s. An account that has **no password** — ' +
             'an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, ' +
@@ -1806,10 +1823,11 @@ export const ROUTES = [
         method: 'POST', path: '/api/client/two-factor/setup', section: 'client-auth',
         summary: 'Starts an authenticator setup and answers its secret and otpauth URL.',
         audience: 'client', auth: 'in_handler', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: clientTwoFactorSetupRequest, response: twoFactorSetupResponse,
+        params: [], query: null, request: clientTwoFactorSetupRequest, requestOptional: true, response: twoFactorSetupResponse,
         errors: ['rate_limited', 'validation_error', 'token_spent', 'unauthorized', 'target_state_conflict'], transport: 'http',
         notes: '**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the ' +
-            'credential; from the app\'s own account settings the app user\'s bearer is, with no challenge. Neither is `401 unauthorized`, and a ' +
+            'credential; from the app\'s own account settings the app user\'s bearer is, with no challenge and an empty or missing body. Neither ' +
+            'is `401 unauthorized`, and a ' +
             'dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app\'s policy is `off`. ' +
             'The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending ' +
             'secret, and an account that already has an authenticator keeps it until the new one is confirmed.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "6.0.0-next.1",
+  "version": "6.0.0-next.2",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",