@fleetless/contracts 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project uses [semantic versioning](https://semver.org/spec/v2.0.0.html) over
 the wire shapes.
 
+## [3.0.0] — 2026-09-22
+
+The protocol window carries over unchanged: `LATEST_BRIDGE_VERSION` is still `4.0.0`, and protocol 2 still sunsets 2026-12-21. Everything below is the REST surface.
+
+### Added
+
+- **Auth-config as three slices, not one document.** `putAppAuthRegistrationRequest` (`self_registration`, `allowed_domains`, `allowed_origins`), `putAppAuthUrlsRequest` (`invite_url`, `verify_url`, `reset_url`) and `putAppAuthMcpRequest` (`mcp_enabled`, `mcp_login_url`) are three `.strict()` replaces behind three new routes — `PUT /api/apps/:id/auth-config/registration`, `/urls` and `/mcp` — each merged server-side against the stored row, so a write to one slice can no longer clear a field it never showed. `GET /api/apps/:id/auth-config` is unchanged and still answers the whole document.
+- **A deletion preview and a delete.** `appDeletionSummary` — six independent counts (`user_count`, `role_count`, `server_key_count`, `invitation_count`, `oidc_provider_count`, `mail_template_count`), deliberately not summed — is what `GET /api/apps/:id/deletion-preview` (`200`) answers and what the `app.deleted` audit event carries, computed by the same function so the confirmation dialog and the eventual receipt cannot quietly disagree. `DELETE /api/apps/:id` (Owner tier, `204`) runs the cascade: an app's users, roles, server keys, invitations, OIDC configuration and mail templates all go; its robots do not, since they belong to the org, not the app. **No `force` parameter** — unlike the robot deletion pair this is modelled on, an app has no open-session state to force past, and inventing one would be a guess wearing a guard's clothes.
+
+### Removed
+
+- **`putAppAuthConfigRequest` and `PUT /api/apps/:id/auth-config`.** Replaced by the three slice requests and routes above — `PUT /api/apps/:id/auth-config/registration`, `PUT /api/apps/:id/auth-config/urls` and `PUT /api/apps/:id/auth-config/mcp`. This is the break that makes this release a major: a caller still sending the old whole-document body finds no route left to send it to.
+
 ## [2.0.0] — 2026-09-22
 
 ### Added

package/artifacts/openapi.json

@@ -924,6 +924,93 @@
             }
           }
         }
+      },
+      "delete": {
+        "operationId": "delete_api_apps_id",
+        "summary": "Deletes an app and everything it produced.",
+        "tags": [
+          "apps"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Success."
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `tier_required`, `invalid_uuid`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "Owner tier, and the gate runs **after** the org-scoped lookup: a developer-tier admin therefore sees the same `404` a stranger would for an app outside their org, rather than a tier refusal that confirms the id exists. A full cascade — its users, roles, server keys, invitations, OIDC provider configuration and mail templates all go, recorded once as `app.deleted` carrying an `appDeletionSummary`. Its robots are untouched: they belong to the org, not to the app. \n\n**No `force` parameter** — see `GET /api/apps/:id/deletion-preview`."
+      }
+    },
+    "/api/apps/{id}/deletion-preview": {
+      "get": {
+        "operationId": "get_api_apps_id_deletion_preview",
+        "summary": "Reports what deleting the app would destroy, without destroying it.",
+        "tags": [
+          "apps"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/app-deletion-summary"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "The same shape the delete's own audit event carries, computed by the same function on purpose: the confirmation dialog and the eventual receipt agree by construction, and any difference between them is real drift rather than two estimates that quietly disagree. \n\n**No `force` parameter, unlike the robot pair this is modelled on.** A robot's open live session is a single nameable state whose interruption is its own hazard, which is why that route makes the caller pass `force` explicitly. An app has no equivalent state to force past, and inventing one would be a guess wearing a guard's clothes — this preview is the guard."
       }
     },
     "/api/apps/{id}/roles": {
@@ -2376,11 +2463,13 @@
             }
           }
         },
-        "description": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider."
-      },
+        "description": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a client-supplied value would be a lie about when the row last changed."
+      }
+    },
+    "/api/apps/{id}/auth-config/registration": {
       "put": {
-        "operationId": "put_api_apps_id_auth_config",
-        "summary": "Replaces the app's auth settings in one write.",
+        "operationId": "put_api_apps_id_auth_config_registration",
+        "summary": "Replaces who may self-register, and from where.",
         "tags": [
           "apps"
         ],
@@ -2422,13 +2511,129 @@
             }
           }
         },
-        "description": "**A replace, not a merge, and `.strict()`**: every field arrives or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are refused in the body — a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. \n\n`400 validation_error` is where the three field rules land: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once, an origin must be a bare scheme-host-port with no path, and a domain must be lowercase. Each refuses at configuration time because each would otherwise fail silently later — a second placeholder leaves one occurrence literal in a mailed link, an origin with a path can never equal a browser's `Origin` header, and a capitalised domain can never match a lowercased address.",
+        "description": "**A replace, not a merge, and `.strict()`**: `self_registration`, `allowed_domains` and `allowed_origins` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. \n\nThe merge is server-side against the stored row, so this write never disturbs the urls or mcp slice.",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/put-app-auth-config-request"
+                "$ref": "#/components/schemas/put-app-auth-registration-request"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/apps/{id}/auth-config/urls": {
+      "put": {
+        "operationId": "put_api_apps_id_auth_config_urls",
+        "summary": "Replaces the three pages Fleetless's mails point at.",
+        "tags": [
+          "apps"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/app-auth-config"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `validation_error`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "**A replace, not a merge, and `.strict()`**: `invite_url`, `verify_url` and `reset_url` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the field rule lands: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once the mail is sent. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or mcp slice.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/put-app-auth-urls-request"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/apps/{id}/auth-config/mcp": {
+      "put": {
+        "operationId": "put_api_apps_id_auth_config_mcp",
+        "summary": "Replaces the MCP switch and its login URL together.",
+        "tags": [
+          "apps"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/app-auth-config"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `validation_error`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "**A replace, not a merge, and `.strict()`**: `mcp_enabled` and `mcp_login_url` both arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`mcp_login_url` answers to the same rule as the `urls` slice's three templates — https (or `http` on `localhost`), its placeholder exactly once — refused as `400 validation_error` rather than left to fail mid-OAuth, in a client's browser where no console screen is watching. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or urls slice.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/put-app-auth-mcp-request"
               }
             }
           }
@@ -8674,6 +8879,56 @@
         ],
         "additionalProperties": false
       },
+      "app-deletion-summary": {
+        "type": "object",
+        "properties": {
+          "user_count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "App users deleted with the app. They are the developer's own customers, not Fleetless users, and exist in no other app."
+          },
+          "role_count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Roles deleted with the app, each with its per-robot slug grants."
+          },
+          "server_key_count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Server keys deleted with the app. A client still holding one is refused at its next request."
+          },
+          "invitation_count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Outstanding invitations — unspent and unexpired — that will never be accepted."
+          },
+          "oidc_provider_count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Identity providers configured for this app. The providers themselves are somebody else's; only this app's configuration of them goes."
+          },
+          "mail_template_count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "Custom mail templates, of at most three. A kind using the Fleetless default text is not counted — there is no row to lose."
+          }
+        },
+        "required": [
+          "user_count",
+          "role_count",
+          "server_key_count",
+          "invitation_count",
+          "oidc_provider_count",
+          "mail_template_count"
+        ],
+        "additionalProperties": false
+      },
       "app-invitation": {
         "type": "object",
         "properties": {
@@ -16318,7 +16573,33 @@
           "message"
         ]
       },
-      "put-app-auth-config-request": {
+      "put-app-auth-mcp-request": {
+        "type": "object",
+        "properties": {
+          "mcp_enabled": {
+            "type": "boolean",
+            "description": "Whether this app serves an MCP endpoint at `/mcp/<identifier>`. Off refuses the whole OAuth surface for the app, not merely the tool calls, and is re-read on every request rather than cached off a token."
+          },
+          "mcp_login_url": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 500
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The page an MCP authorization redirects to, with `{interaction}` where the interaction id goes. Not a token: the id names a pending request the server already holds, and the app authenticates the user itself before approving it."
+          }
+        },
+        "required": [
+          "mcp_enabled",
+          "mcp_login_url"
+        ],
+        "additionalProperties": false
+      },
+      "put-app-auth-registration-request": {
         "type": "object",
         "properties": {
           "self_registration": {
@@ -16344,11 +16625,18 @@
               "maxLength": 200
             },
             "description": "The origins the client auth API answers CORS for, and the only origins an OIDC `redirect_uri` may name. Bare origins: scheme, host and port, with no path — a browser sends nothing longer, so an entry carrying one could never match."
-          },
-          "mcp_enabled": {
-            "type": "boolean",
-            "description": "Whether this app serves an MCP endpoint at `/mcp/<identifier>`. Off refuses the whole OAuth surface for the app, not merely the tool calls, and is re-read on every request rather than cached off a token."
-          },
+          }
+        },
+        "required": [
+          "self_registration",
+          "allowed_domains",
+          "allowed_origins"
+        ],
+        "additionalProperties": false
+      },
+      "put-app-auth-urls-request": {
+        "type": "object",
+        "properties": {
           "invite_url": {
             "anyOf": [
               {
@@ -16384,29 +16672,12 @@
               }
             ],
             "description": "The page that takes a new password, with `{token}` where the token goes."
-          },
-          "mcp_login_url": {
-            "anyOf": [
-              {
-                "type": "string",
-                "maxLength": 500
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The page an MCP authorization redirects to, with `{interaction}` where the interaction id goes. Not a token: the id names a pending request the server already holds, and the app authenticates the user itself before approving it."
           }
         },
         "required": [
-          "self_registration",
-          "allowed_domains",
-          "allowed_origins",
-          "mcp_enabled",
           "invite_url",
           "verify_url",
-          "reset_url",
-          "mcp_login_url"
+          "reset_url"
         ],
         "additionalProperties": false
       },

package/artifacts/routes.json

@@ -487,6 +487,65 @@
       "transport": "http",
       "notes": "A `default_role_id` naming a role of another app is refused: it is the one cross-app authorization check this shape can carry. Changing the robot set closes every live subscription the app's users hold, since a grant may no longer name a reachable robot."
     },
+    {
+      "method": "GET",
+      "path": "/api/apps/:id/deletion-preview",
+      "section": "apps",
+      "summary": "Reports what deleting the app would destroy, without destroying it.",
+      "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`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "app-deletion-summary",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "The same shape the delete's own audit event carries, computed by the same function on purpose: the confirmation dialog and the eventual receipt agree by construction, and any difference between them is real drift rather than two estimates that quietly disagree. \n\n**No `force` parameter, unlike the robot pair this is modelled on.** A robot's open live session is a single nameable state whose interruption is its own hazard, which is why that route makes the caller pass `force` explicitly. An app has no equivalent state to force past, and inventing one would be a guess wearing a guard's clothes — this preview is the guard."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/apps/:id",
+      "section": "apps",
+      "summary": "Deletes an app and everything it produced.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 204,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "Owner tier, and the gate runs **after** the org-scoped lookup: a developer-tier admin therefore sees the same `404` a stranger would for an app outside their org, rather than a tier refusal that confirms the id exists. A full cascade — its users, roles, server keys, invitations, OIDC provider configuration and mail templates all go, recorded once as `app.deleted` carrying an `appDeletionSummary`. Its robots are untouched: they belong to the org, not to the app. \n\n**No `force` parameter** — see `GET /api/apps/:id/deletion-preview`."
+    },
     {
       "method": "POST",
       "path": "/api/apps/:id/roles",
@@ -1360,13 +1419,73 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider."
+      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a client-supplied value would be a lie about when the row last changed."
     },
     {
       "method": "PUT",
-      "path": "/api/apps/:id/auth-config",
+      "path": "/api/apps/:id/auth-config/registration",
+      "section": "apps",
+      "summary": "Replaces who may self-register, and from where.",
+      "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`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-registration-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, not a merge, and `.strict()`**: `self_registration`, `allowed_domains` and `allowed_origins` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. \n\nThe merge is server-side against the stored row, so this write never disturbs the urls or mcp slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/urls",
+      "section": "apps",
+      "summary": "Replaces the three pages Fleetless's mails point at.",
+      "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`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-urls-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, not a merge, and `.strict()`**: `invite_url`, `verify_url` and `reset_url` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the field rule lands: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once the mail is sent. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or mcp slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/mcp",
       "section": "apps",
-      "summary": "Replaces the app's auth settings in one write.",
+      "summary": "Replaces the MCP switch and its login URL together.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -1379,7 +1498,7 @@
         }
       ],
       "query": null,
-      "request": "put-app-auth-config-request",
+      "request": "put-app-auth-mcp-request",
       "response": "app-auth-config",
       "errors": [
         "unauthorized",
@@ -1390,7 +1509,7 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "**A replace, not a merge, and `.strict()`**: every field arrives or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are refused in the body — a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. \n\n`400 validation_error` is where the three field rules land: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once, an origin must be a bare scheme-host-port with no path, and a domain must be lowercase. Each refuses at configuration time because each would otherwise fail silently later — a second placeholder leaves one occurrence literal in a mailed link, an origin with a path can never equal a browser's `Origin` header, and a capitalised domain can never match a lowercased address."
+      "notes": "**A replace, not a merge, and `.strict()`**: `mcp_enabled` and `mcp_login_url` both arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`mcp_login_url` answers to the same rule as the `urls` slice's three templates — https (or `http` on `localhost`), its placeholder exactly once — refused as `400 validation_error` rather than left to fail mid-OAuth, in a client's browser where no console screen is watching. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or urls slice."
     },
     {
       "method": "GET",

package/artifacts/schema/app-deletion-summary.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "user_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "App users deleted with the app. They are the developer's own customers, not Fleetless users, and exist in no other app."
+    },
+    "role_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Roles deleted with the app, each with its per-robot slug grants."
+    },
+    "server_key_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Server keys deleted with the app. A client still holding one is refused at its next request."
+    },
+    "invitation_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Outstanding invitations — unspent and unexpired — that will never be accepted."
+    },
+    "oidc_provider_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Identity providers configured for this app. The providers themselves are somebody else's; only this app's configuration of them goes."
+    },
+    "mail_template_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Custom mail templates, of at most three. A kind using the Fleetless default text is not counted — there is no row to lose."
+    }
+  },
+  "required": [
+    "user_count",
+    "role_count",
+    "server_key_count",
+    "invitation_count",
+    "oidc_provider_count",
+    "mail_template_count"
+  ],
+  "additionalProperties": false
+}

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

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

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

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "self_registration": {
+      "type": "boolean",
+      "description": "Whether a stranger may create an account in this app. Off refuses `POST /api/client/register` with `403 registration_closed`, and refuses an unknown identity at an OIDC callback with the same reasoning — one switch for one decision, whichever door the person arrives at."
+    },
+    "allowed_domains": {
+      "maxItems": 50,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 253,
+        "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
+      },
+      "description": "The email domains self-registration accepts, lowercase. An empty list means no domain restriction, not \"nobody\" — the switch above is what closes the door. **An invitation always bypasses this**, by password and through a provider alike."
+    },
+    "allowed_origins": {
+      "maxItems": 20,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 200
+      },
+      "description": "The origins the client auth API answers CORS for, and the only origins an OIDC `redirect_uri` may name. Bare origins: scheme, host and port, with no path — a browser sends nothing longer, so an entry carrying one could never match."
+    }
+  },
+  "required": [
+    "self_registration",
+    "allowed_domains",
+    "allowed_origins"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "invite_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "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."
+    },
+    "verify_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "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."
+    },
+    "reset_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page that takes a new password, with `{token}` where the token goes."
+    }
+  },
+  "required": [
+    "invite_url",
+    "verify_url",
+    "reset_url"
+  ],
+  "additionalProperties": false
+}

package/dist/app-users.d.ts

@@ -400,23 +400,41 @@ export declare const appAuthConfig: z.ZodObject<{
 }, z.core.$strip>;
 export type AppAuthConfig = z.infer<typeof appAuthConfig>;
 /**
- * `PUT /api/apps/:id/auth-config` — a replace, not a merge, and `.strict()`.
+ * `PUT /api/apps/:id/auth-config/registration` — who may get in, and from
+ * where.
  *
- * `oidc_callback_url` and `updated_at` are omitted because both are the
- * server's: see the callback URL's own note for why a writable one would be a
- * redirect-target hole rather than a convenience.
+ * Three slices rather than one document, and each still a **replace** with
+ * every field of its slice required: three screens carving up one
+ * all-required request is how a field nobody's screen shows becomes a field
+ * somebody's save clears. The slice states its own ownership, so a new field
+ * lands in one schema and one screen.
+ *
+ * The merge is the server's, against the stored row — never the caller's,
+ * whose copy may be older than the row it would overwrite.
  */
-export declare const putAppAuthConfigRequest: z.ZodObject<{
+export declare const putAppAuthRegistrationRequest: z.ZodObject<{
     self_registration: z.ZodBoolean;
     allowed_domains: z.ZodArray<z.ZodString>;
     allowed_origins: z.ZodArray<z.ZodString>;
-    mcp_enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export type PutAppAuthRegistrationRequest = z.infer<typeof putAppAuthRegistrationRequest>;
+/** `PUT /api/apps/:id/auth-config/urls` — the three pages Fleetless's mails point at. */
+export declare const putAppAuthUrlsRequest: z.ZodObject<{
     invite_url: z.ZodNullable<z.ZodString>;
     verify_url: z.ZodNullable<z.ZodString>;
     reset_url: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type PutAppAuthUrlsRequest = z.infer<typeof putAppAuthUrlsRequest>;
+/**
+ * `PUT /api/apps/:id/auth-config/mcp` — the switch and the login URL, which
+ * belong together: on without a URL refuses every sign-in, in the MCP
+ * client's browser mid-OAuth, where no console screen ever sees it.
+ */
+export declare const putAppAuthMcpRequest: z.ZodObject<{
+    mcp_enabled: z.ZodBoolean;
     mcp_login_url: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
-export type PutAppAuthConfigRequest = z.infer<typeof putAppAuthConfigRequest>;
+export type PutAppAuthMcpRequest = z.infer<typeof putAppAuthMcpRequest>;
 /**
  * The three mails a developer may replace with their own template.
  * Mails to *Fleetless* users — a team invitation, a console password reset —

package/dist/app-users.js

@@ -481,14 +481,32 @@ export const appAuthConfig = z.object({
     updated_at: z.iso.datetime().meta({ description: 'When the configuration was last written, as an ISO 8601 timestamp.' }),
 });
 /**
- * `PUT /api/apps/:id/auth-config` — a replace, not a merge, and `.strict()`.
+ * `PUT /api/apps/:id/auth-config/registration` — who may get in, and from
+ * where.
  *
- * `oidc_callback_url` and `updated_at` are omitted because both are the
- * server's: see the callback URL's own note for why a writable one would be a
- * redirect-target hole rather than a convenience.
+ * Three slices rather than one document, and each still a **replace** with
+ * every field of its slice required: three screens carving up one
+ * all-required request is how a field nobody's screen shows becomes a field
+ * somebody's save clears. The slice states its own ownership, so a new field
+ * lands in one schema and one screen.
+ *
+ * The merge is the server's, against the stored row — never the caller's,
+ * whose copy may be older than the row it would overwrite.
+ */
+export const putAppAuthRegistrationRequest = appAuthConfig
+    .pick({ self_registration: true, allowed_domains: true, allowed_origins: true })
+    .strict();
+/** `PUT /api/apps/:id/auth-config/urls` — the three pages Fleetless's mails point at. */
+export const putAppAuthUrlsRequest = appAuthConfig
+    .pick({ invite_url: true, verify_url: true, reset_url: true })
+    .strict();
+/**
+ * `PUT /api/apps/:id/auth-config/mcp` — the switch and the login URL, which
+ * belong together: on without a URL refuses every sign-in, in the MCP
+ * client's browser mid-OAuth, where no console screen ever sees it.
  */
-export const putAppAuthConfigRequest = appAuthConfig
-    .omit({ oidc_callback_url: true, updated_at: true })
+export const putAppAuthMcpRequest = appAuthConfig
+    .pick({ mcp_enabled: true, mcp_login_url: true })
     .strict();
 /**
  * The three mails a developer may replace with their own template.

package/dist/apps.d.ts

@@ -42,6 +42,28 @@ export declare const appListResponse: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AppListResponse = z.infer<typeof appListResponse>;
+/**
+ * What deleting an app would destroy — read before the irreversible click,
+ * and carried again by the `app.deleted` audit event.
+ *
+ * **Six numbers, never a sum**, for the reason `robotDeletionSummary` states
+ * at length: the console reads this aloud as one sentence, and a total would
+ * describe six unrelated magnitudes with one figure on the one screen whose
+ * entire justification is naming what cannot be undone.
+ *
+ * Robots are not here because they do not go: they belong to the
+ * organization, not to the app. The audit trail is not here either — a record
+ * of what happened outlives the thing it happened to.
+ */
+export declare const appDeletionSummary: z.ZodObject<{
+    user_count: z.ZodNumber;
+    role_count: z.ZodNumber;
+    server_key_count: z.ZodNumber;
+    invitation_count: z.ZodNumber;
+    oidc_provider_count: z.ZodNumber;
+    mail_template_count: z.ZodNumber;
+}, z.core.$strip>;
+export type AppDeletionSummary = z.infer<typeof appDeletionSummary>;
 /**
  * **`robot_ids` is accepted here, and `.strict()` catches everything else.**
  * A create shape carrying `name` and `identifier` only would let zod strip an

package/dist/apps.js

@@ -78,6 +78,39 @@ export const appListResponse = z.object({
         description: 'Every app of the caller\'s organisation, oldest first by `created_at`. The org scope is the whole filter — there is no id to narrow by and nothing to refuse.',
     }),
 });
+/**
+ * What deleting an app would destroy — read before the irreversible click,
+ * and carried again by the `app.deleted` audit event.
+ *
+ * **Six numbers, never a sum**, for the reason `robotDeletionSummary` states
+ * at length: the console reads this aloud as one sentence, and a total would
+ * describe six unrelated magnitudes with one figure on the one screen whose
+ * entire justification is naming what cannot be undone.
+ *
+ * Robots are not here because they do not go: they belong to the
+ * organization, not to the app. The audit trail is not here either — a record
+ * of what happened outlives the thing it happened to.
+ */
+export const appDeletionSummary = z.object({
+    user_count: z.number().int().nonnegative().meta({
+        description: 'App users deleted with the app. They are the developer\'s own customers, not Fleetless users, and exist in no other app.',
+    }),
+    role_count: z.number().int().nonnegative().meta({
+        description: 'Roles deleted with the app, each with its per-robot slug grants.',
+    }),
+    server_key_count: z.number().int().nonnegative().meta({
+        description: 'Server keys deleted with the app. A client still holding one is refused at its next request.',
+    }),
+    invitation_count: z.number().int().nonnegative().meta({
+        description: 'Outstanding invitations — unspent and unexpired — that will never be accepted.',
+    }),
+    oidc_provider_count: z.number().int().nonnegative().meta({
+        description: 'Identity providers configured for this app. The providers themselves are somebody else\'s; only this app\'s configuration of them goes.',
+    }),
+    mail_template_count: z.number().int().nonnegative().meta({
+        description: 'Custom mail templates, of at most three. A kind using the Fleetless default text is not counted — there is no row to lose.',
+    }),
+});
 /**
  * **`robot_ids` is accepted here, and `.strict()` catches everything else.**
  * A create shape carrying `name` and `identifier` only would let zod strip an

package/dist/index.d.ts

@@ -31,14 +31,14 @@ export { clientAuth, authOk, authError, clientInvoke, clientCancel, clientPublis
 export type { ClientAuth, AuthOk, AuthError, ClientInvoke, ClientCancel, ClientPublish, CommandResult, ErrorFrame, ClientSubscribe, ClientUnsubscribe, SubscribeError, DatapointEvent, ResourceHealthEvent, ResourceHealthCleared, LiveSessionEndReason, LiveSessionEvent, OrgEventKind, OrgEventSeverity, OrgEvent, OrgEventSubscribe, OrgEventUnsubscribe, OrgEventReplay, OrgEventDropped, } from './realtime.js';
 export { password, org, patchOrgResponse, sessionTokens, refreshRequest, signUpRequest, signUpResponse, waitlistRequest, developerLoginRequest, USER_DISPLAY_NAME_MAX, orgAdminTier, fleetlessUser, fleetlessUserListResponse, createTeamInviteRequest, teamInvite, pendingTeamInvite, pendingTeamInviteListResponse, acceptTeamInviteRequest, patchFleetlessUserRequest, tierChangeRequest, mailStatus, tierRequiredDetails, passwordChangeRequest, passwordResetRequest, passwordResetConfirm, idpIssuer, authMeResponse, patchOrgRequest, patchAuthMeRequest, } from './identity.js';
 export type { Org, PatchOrgResponse, SessionTokens, RefreshRequest, SignUpRequest, SignUpResponse, WaitlistRequest, DeveloperLoginRequest, OrgAdminTier, FleetlessUser, FleetlessUserListResponse, CreateTeamInviteRequest, TeamInvite, PendingTeamInvite, PendingTeamInviteListResponse, AcceptTeamInviteRequest, PatchFleetlessUserRequest, TierChangeRequest, MailStatus, TierRequiredDetails, PasswordChangeRequest, PasswordResetRequest, PasswordResetConfirm, IdpIssuer, AuthMeResponse, PatchOrgRequest, PatchAuthMeRequest, } from './identity.js';
-export { appIdentifier, app, appListResponse, createAppRequest, updateAppRequest, serverKeyToken, serverKey, serverKeyListResponse, createServerKeyResponse, role, roleListResponse, rolePermissions, } from './apps.js';
-export type { App, AppListResponse, CreateAppRequest, UpdateAppRequest, ServerKey, ServerKeyListResponse, CreateServerKeyResponse, Role, RoleListResponse, RolePermissions, } from './apps.js';
+export { appIdentifier, app, appListResponse, appDeletionSummary, createAppRequest, updateAppRequest, serverKeyToken, serverKey, serverKeyListResponse, createServerKeyResponse, role, roleListResponse, rolePermissions, } from './apps.js';
+export type { App, AppListResponse, AppDeletionSummary, CreateAppRequest, UpdateAppRequest, ServerKey, ServerKeyListResponse, CreateServerKeyResponse, Role, RoleListResponse, RolePermissions, } from './apps.js';
 export { clientLoginRequest, clientRefreshRequest, clientLogoutRequest, clientRegisterRequest, clientVerifyEmailRequest, clientResendVerificationRequest, clientPasswordResetRequest, clientPasswordResetConfirmRequest, clientAcceptInvitationRequest, CLIENT_OIDC_CALLBACK_PATH, clientProviderListQuery, clientProviderListResponse, clientOidcStartQuery, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcErrorCode, clientMcpInteraction, clientMcpInteractionDecisionResponse, mcpConsentGrant, mcpConsentGrantListResponse, clientIdentity, } from './client-auth.js';
 export type { ClientLoginRequest, ClientRefreshRequest, ClientLogoutRequest, ClientRegisterRequest, ClientVerifyEmailRequest, ClientResendVerificationRequest, ClientPasswordResetRequest, ClientPasswordResetConfirmRequest, ClientAcceptInvitationRequest, ClientProviderListQuery, ClientProviderListResponse, ClientOidcStartQuery, ClientOidcCallbackQuery, ClientOidcExchangeRequest, ClientOidcErrorCode, ClientMcpInteraction, ClientMcpInteractionDecisionResponse, McpConsentGrant, McpConsentGrantListResponse, ClientIdentity, } from './client-auth.js';
 export { clientRobotListItem, clientRobotListResponse } from './client-robots.js';
 export type { ClientRobotListItem, ClientRobotListResponse } from './client-robots.js';
-export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthConfigRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
-export type { AppUserStatus, AppUser, AppUserListResponse, CreateAppUserRequest, PatchAppUserRequest, CreateAppInvitationRequest, AppInvitation, PendingAppInvitation, AppInvitationListResponse, AppOidcProvider, AppOidcProviderListResponse, CreateAppOidcProviderRequest, PatchAppOidcProviderRequest, AppAuthConfig, PutAppAuthConfigRequest, MailTemplateKind, AppMailTemplate, AppMailTemplateListResponse, PutAppMailTemplateRequest, MailTemplatePreviewRequest, MailTemplatePreviewResponse, MailTemplateProblemDetails, MailOutcome, } from './app-users.js';
+export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthRegistrationRequest, putAppAuthUrlsRequest, putAppAuthMcpRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
+export type { AppUserStatus, AppUser, AppUserListResponse, CreateAppUserRequest, PatchAppUserRequest, CreateAppInvitationRequest, AppInvitation, PendingAppInvitation, AppInvitationListResponse, AppOidcProvider, AppOidcProviderListResponse, CreateAppOidcProviderRequest, PatchAppOidcProviderRequest, AppAuthConfig, PutAppAuthRegistrationRequest, PutAppAuthUrlsRequest, PutAppAuthMcpRequest, MailTemplateKind, AppMailTemplate, AppMailTemplateListResponse, PutAppMailTemplateRequest, MailTemplatePreviewRequest, MailTemplatePreviewResponse, MailTemplateProblemDetails, MailOutcome, } from './app-users.js';
 export { assetKind, URDF_ASSET_NAME, asset, urdfCompleteness, assetListResponse, assetsClearResponse, missingAssetQuery, assetSyncRequest, assetSyncResponse, assetSyncState, assetSyncStatus, assetFailure, assetFailureKind, assetStoreRefusedDetails, assetSyncBusyDetails, ROBOT_ASSET_STORE_BYTES, } from './assets.js';
 export type { AssetKind, Asset, UrdfCompleteness, AssetListResponse, AssetsClearResponse, MissingAssetQuery, AssetSyncRequest, AssetSyncResponse, AssetSyncState, AssetSyncStatus, AssetFailure, AssetFailureKind, AssetStoreRefusedDetails, AssetSyncBusyDetails, } from './assets.js';
 export { auditActor, auditEvent, auditQuery, auditListResponse, AUDIT_CSV_COLUMNS, AUDIT_RETENTION_DAYS } from './audit.js';

package/dist/index.js

@@ -38,11 +38,11 @@ USER_DISPLAY_NAME_MAX, orgAdminTier, fleetlessUser, fleetlessUserListResponse, c
 mailStatus, tierRequiredDetails, passwordChangeRequest, passwordResetRequest, passwordResetConfirm, idpIssuer, 
 // auth/me, org and member patches.
 authMeResponse, patchOrgRequest, patchAuthMeRequest, } from './identity.js';
-export { appIdentifier, app, appListResponse, createAppRequest, updateAppRequest, serverKeyToken, serverKey, serverKeyListResponse, createServerKeyResponse, role, roleListResponse, rolePermissions, } from './apps.js';
+export { appIdentifier, app, appListResponse, appDeletionSummary, createAppRequest, updateAppRequest, serverKeyToken, serverKey, serverKeyListResponse, createServerKeyResponse, role, roleListResponse, rolePermissions, } from './apps.js';
 export { clientLoginRequest, clientRefreshRequest, clientLogoutRequest, clientRegisterRequest, clientVerifyEmailRequest, clientResendVerificationRequest, clientPasswordResetRequest, clientPasswordResetConfirmRequest, clientAcceptInvitationRequest, CLIENT_OIDC_CALLBACK_PATH, clientProviderListQuery, clientProviderListResponse, clientOidcStartQuery, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcErrorCode, clientMcpInteraction, clientMcpInteractionDecisionResponse, mcpConsentGrant, mcpConsentGrantListResponse, clientIdentity, } from './client-auth.js';
 export { clientRobotListItem, clientRobotListResponse } from './client-robots.js';
 // The per-app identity space.
-export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthConfigRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
+export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLES, DEFAULT_MAIL_TEMPLATES, providerSlug, appUserStatus, appUser, appUserListResponse, createAppUserRequest, patchAppUserRequest, createAppInvitationRequest, appInvitation, pendingAppInvitation, appInvitationListResponse, appOidcProvider, appOidcProviderListResponse, createAppOidcProviderRequest, patchAppOidcProviderRequest, appUrlTemplate, allowedOrigin, emailDomain, appAuthConfig, putAppAuthRegistrationRequest, putAppAuthUrlsRequest, putAppAuthMcpRequest, mailTemplateKind, appMailTemplate, appMailTemplateListResponse, putAppMailTemplateRequest, mailTemplatePreviewRequest, mailTemplatePreviewResponse, mailTemplateProblemDetails, mailOutcome, } from './app-users.js';
 export { assetKind, URDF_ASSET_NAME, asset, urdfCompleteness, assetListResponse, assetsClearResponse, missingAssetQuery, assetSyncRequest, assetSyncResponse, assetSyncState, assetSyncStatus, assetFailure, assetFailureKind, assetStoreRefusedDetails, assetSyncBusyDetails, ROBOT_ASSET_STORE_BYTES, } from './assets.js';
 export { auditActor, auditEvent, auditQuery, auditListResponse, AUDIT_CSV_COLUMNS, AUDIT_RETENTION_DAYS } from './audit.js';
 export { alertRowCondition, alertSeverity, alertState, datapointAlertRow, alertListResponse, orgFiringAlertsResponse, orgAlertsQuery, datapointDisplay, putDatapointDisplayRequest, } from './alerts.js';

package/dist/rest.d.ts

@@ -1440,6 +1440,8 @@ export type HistoryResponse = z.infer<typeof historyResponse>;
  * |---|---|---|
  * | `DELETE /api/robots/:id` | — | `204`. `?force=true` to proceed while a live session is open; without it, `409 robot_in_use` |
  * | `GET /api/robots/:id/deletion-preview` | — | `robotDeletionSummary` — the same shape the audit event carries |
+ * | `DELETE /api/apps/:id` | — | `204`. No `force` parameter — an app has no open-session hazard to force past, so the preview is the guard |
+ * | `GET /api/apps/:id/deletion-preview` | — | `appDeletionSummary` — the same shape the audit event carries |
  * | `GET /api/org/health` | — | `resourceHealthListResponse`; `?robot_id=` narrows it to one robot |
  *
  * Plus `resourceHealthEvent`, pushed on the **developer** realtime socket

package/dist/rest.js

@@ -1228,6 +1228,8 @@ export const historyResponse = z.union([historySamplesResponse, historyBucketsRe
  * |---|---|---|
  * | `DELETE /api/robots/:id` | — | `204`. `?force=true` to proceed while a live session is open; without it, `409 robot_in_use` |
  * | `GET /api/robots/:id/deletion-preview` | — | `robotDeletionSummary` — the same shape the audit event carries |
+ * | `DELETE /api/apps/:id` | — | `204`. No `force` parameter — an app has no open-session hazard to force past, so the preview is the guard |
+ * | `GET /api/apps/:id/deletion-preview` | — | `appDeletionSummary` — the same shape the audit event carries |
  * | `GET /api/org/health` | — | `resourceHealthListResponse`; `?robot_id=` narrows it to one robot |
  *
  * Plus `resourceHealthEvent`, pushed on the **developer** realtime socket

package/dist/routes.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
-import { appListResponse, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, rolePermissions, serverKeyListResponse, updateAppRequest, } from './apps.js';
+import { appListResponse, appDeletionSummary, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, rolePermissions, serverKeyListResponse, updateAppRequest, } from './apps.js';
 import { alertListResponse, orgAlertsQuery, orgFiringAlertsResponse } from './alerts.js';
 import { asset, assetListResponse, assetsClearResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
 import { auditListResponse, auditQuery } from './audit.js';
 import { CLIENT_OIDC_CALLBACK_PATH, clientAcceptInvitationRequest, clientIdentity, clientLoginRequest, clientLogoutRequest, clientMcpInteraction, clientMcpInteractionDecisionResponse, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcStartQuery, clientPasswordResetConfirmRequest, clientPasswordResetRequest, clientProviderListQuery, clientProviderListResponse, clientRefreshRequest, clientRegisterRequest, clientResendVerificationRequest, clientVerifyEmailRequest, mcpConsentGrantListResponse, } from './client-auth.js';
 import { clientRobotListResponse } from './client-robots.js';
-import { appAuthConfig, appInvitation, appInvitationListResponse, appMailTemplate, appMailTemplateListResponse, appOidcProvider, appOidcProviderListResponse, appUser, appUserListResponse, createAppInvitationRequest, createAppOidcProviderRequest, createAppUserRequest, mailOutcome, mailTemplatePreviewRequest, mailTemplatePreviewResponse, patchAppOidcProviderRequest, patchAppUserRequest, putAppAuthConfigRequest, putAppMailTemplateRequest, } from './app-users.js';
+import { appAuthConfig, appInvitation, appInvitationListResponse, appMailTemplate, appMailTemplateListResponse, appOidcProvider, appOidcProviderListResponse, appUser, appUserListResponse, createAppInvitationRequest, createAppOidcProviderRequest, createAppUserRequest, mailOutcome, mailTemplatePreviewRequest, mailTemplatePreviewResponse, patchAppOidcProviderRequest, patchAppUserRequest, putAppAuthMcpRequest, putAppAuthRegistrationRequest, putAppAuthUrlsRequest, putAppMailTemplateRequest, } from './app-users.js';
 import { acceptTeamInviteRequest, authMeResponse, createTeamInviteRequest, fleetlessUser, fleetlessUserListResponse, passwordChangeRequest, passwordResetConfirm, passwordResetRequest, patchAuthMeRequest, patchFleetlessUserRequest, patchOrgRequest, patchOrgResponse, pendingTeamInviteListResponse, refreshRequest, sessionTokens, signUpRequest, signUpResponse, teamInvite, tierChangeRequest, waitlistRequest, } from './identity.js';
 import { jobRunListResponse, jobRunQuery, jobRunSummary, jobRunSummaryQuery } from './jobs.js';
 import { MCP_APP_PATHS, mcpRobotDatasheet, mcpRolePreviewResponse } from './mcp.js';
@@ -295,6 +295,32 @@ export const ROUTES = [
         notes: 'A `default_role_id` naming a role of another app is refused: it is the one cross-app authorization check this shape can carry. ' +
             'Changing the robot set closes every live subscription the app\'s users hold, since a grant may no longer name a reachable robot.',
     },
+    {
+        method: 'GET', path: '/api/apps/:id/deletion-preview', section: 'apps',
+        summary: 'Reports what deleting the app would destroy, without destroying it.',
+        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`.' }],
+        query: null, request: null, response: appDeletionSummary,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
+        notes: 'The same shape the delete\'s own audit event carries, computed by the same function on purpose: the confirmation dialog and the eventual ' +
+            'receipt agree by construction, and any difference between them is real drift rather than two estimates that quietly disagree. \n\n' +
+            '**No `force` parameter, unlike the robot pair this is modelled on.** A robot\'s open live session is a single nameable state whose ' +
+            'interruption is its own hazard, which is why that route makes the caller pass `force` explicitly. An app has no equivalent state to ' +
+            'force past, and inventing one would be a guess wearing a guard\'s clothes — this preview is the guard.',
+    },
+    {
+        method: 'DELETE', path: '/api/apps/:id', section: 'apps',
+        summary: 'Deletes an app and everything it produced.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: true, status: 204,
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
+        query: null, request: null, response: null,
+        errors: [...DEVELOPER_GUARD, 'tier_required', 'invalid_uuid', 'not_found'], transport: 'http',
+        notes: 'Owner tier, and the gate runs **after** the org-scoped lookup: a developer-tier admin therefore sees the same `404` a stranger would ' +
+            'for an app outside their org, rather than a tier refusal that confirms the id exists. A full cascade — its users, roles, server keys, ' +
+            'invitations, OIDC provider configuration and mail templates all go, recorded once as `app.deleted` carrying an `appDeletionSummary`. ' +
+            'Its robots are untouched: they belong to the org, not to the app. \n\n**No `force` parameter** — see ' +
+            '`GET /api/apps/:id/deletion-preview`.',
+    },
     {
         method: 'POST', path: '/api/apps/:id/roles', section: 'apps',
         summary: 'Creates a custom role on the app.',
@@ -681,22 +707,55 @@ export const ROUTES = [
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
         notes: 'One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a ' +
             '`404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same ' +
-            'for every app and every provider, and is the value a developer registers at their identity provider.',
+            'for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice ' +
+            'write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an ' +
+            'authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a ' +
+            'client-supplied value would be a lie about when the row last changed.',
+    },
+    {
+        method: 'PUT', path: '/api/apps/:id/auth-config/registration', section: 'apps',
+        summary: 'Replaces who may self-register, and from where.',
+        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`.' }],
+        query: null, request: putAppAuthRegistrationRequest, response: appAuthConfig,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
+        notes: '**A replace, not a merge, and `.strict()`**: `self_registration`, `allowed_domains` and `allowed_origins` all arrive or the write is ' +
+            'refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and ' +
+            '`updated_at` are the server\'s, refused in this body as in every slice\'s — see `GET`\'s notes for why. ' +
+            '\n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one ' +
+            'can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser ' +
+            'sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. ' +
+            '\n\nThe merge is server-side against the stored row, so this write never disturbs the urls or mcp slice.',
+    },
+    {
+        method: 'PUT', path: '/api/apps/:id/auth-config/urls', section: 'apps',
+        summary: "Replaces the three pages Fleetless's mails point at.",
+        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`.' }],
+        query: null, request: putAppAuthUrlsRequest, response: appAuthConfig,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
+        notes: '**A replace, not a merge, and `.strict()`**: `invite_url`, `verify_url` and `reset_url` all arrive or the write is refused, so a ' +
+            'client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are ' +
+            'the server\'s, refused in this body as in every slice\'s — see `GET`\'s notes for why. ' +
+            '\n\n`400 validation_error` is where the field rule lands: a URL template must be https (or `http` on `localhost`) and carry its ' +
+            'placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once ' +
+            'the mail is sent. ' +
+            '\n\nThe merge is server-side against the stored row, so this write never disturbs the registration or mcp slice.',
     },
     {
-        method: 'PUT', path: '/api/apps/:id/auth-config', section: 'apps',
-        summary: "Replaces the app's auth settings in one write.",
+        method: 'PUT', path: '/api/apps/:id/auth-config/mcp', section: 'apps',
+        summary: 'Replaces the MCP switch and its login URL together.',
         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`.' }],
-        query: null, request: putAppAuthConfigRequest, response: appAuthConfig,
+        query: null, request: putAppAuthMcpRequest, response: appAuthConfig,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
-        notes: '**A replace, not a merge, and `.strict()`**: every field arrives or the write is refused, so a client built against an older shape ' +
-            'cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are refused in the body — a writable ' +
-            'callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. ' +
-            '\n\n`400 validation_error` is where the three field rules land: a URL template must be https (or `http` on `localhost`) and carry its ' +
-            'placeholder exactly once, an origin must be a bare scheme-host-port with no path, and a domain must be lowercase. Each refuses at ' +
-            'configuration time because each would otherwise fail silently later — a second placeholder leaves one occurrence literal in a mailed ' +
-            'link, an origin with a path can never equal a browser\'s `Origin` header, and a capitalised domain can never match a lowercased address.',
+        notes: '**A replace, not a merge, and `.strict()`**: `mcp_enabled` and `mcp_login_url` both arrive or the write is refused, so a client built ' +
+            'against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server\'s, ' +
+            'refused in this body as in every slice\'s — see `GET`\'s notes for why. ' +
+            '\n\n`mcp_login_url` answers to the same rule as the `urls` slice\'s three templates — https (or `http` on `localhost`), its placeholder ' +
+            'exactly once — refused as `400 validation_error` rather than left to fail mid-OAuth, in a client\'s browser where no console screen ' +
+            'is watching. ' +
+            '\n\nThe merge is server-side against the stored row, so this write never disturbs the registration or urls slice.',
     },
     {
         method: 'GET', path: '/api/apps/:id/mail-templates', section: 'apps',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "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",

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

@@ -1,93 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "self_registration": {
-      "type": "boolean",
-      "description": "Whether a stranger may create an account in this app. Off refuses `POST /api/client/register` with `403 registration_closed`, and refuses an unknown identity at an OIDC callback with the same reasoning — one switch for one decision, whichever door the person arrives at."
-    },
-    "allowed_domains": {
-      "maxItems": 50,
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1,
-        "maxLength": 253,
-        "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
-      },
-      "description": "The email domains self-registration accepts, lowercase. An empty list means no domain restriction, not \"nobody\" — the switch above is what closes the door. **An invitation always bypasses this**, by password and through a provider alike."
-    },
-    "allowed_origins": {
-      "maxItems": 20,
-      "type": "array",
-      "items": {
-        "type": "string",
-        "maxLength": 200
-      },
-      "description": "The origins the client auth API answers CORS for, and the only origins an OIDC `redirect_uri` may name. Bare origins: scheme, host and port, with no path — a browser sends nothing longer, so an entry carrying one could never match."
-    },
-    "mcp_enabled": {
-      "type": "boolean",
-      "description": "Whether this app serves an MCP endpoint at `/mcp/<identifier>`. Off refuses the whole OAuth surface for the app, not merely the tool calls, and is re-read on every request rather than cached off a token."
-    },
-    "invite_url": {
-      "anyOf": [
-        {
-          "type": "string",
-          "maxLength": 500
-        },
-        {
-          "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."
-    },
-    "verify_url": {
-      "anyOf": [
-        {
-          "type": "string",
-          "maxLength": 500
-        },
-        {
-          "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."
-    },
-    "reset_url": {
-      "anyOf": [
-        {
-          "type": "string",
-          "maxLength": 500
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "The page that takes a new password, with `{token}` where the token goes."
-    },
-    "mcp_login_url": {
-      "anyOf": [
-        {
-          "type": "string",
-          "maxLength": 500
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "The page an MCP authorization redirects to, with `{interaction}` where the interaction id goes. Not a token: the id names a pending request the server already holds, and the app authenticates the user itself before approving it."
-    }
-  },
-  "required": [
-    "self_registration",
-    "allowed_domains",
-    "allowed_origins",
-    "mcp_enabled",
-    "invite_url",
-    "verify_url",
-    "reset_url",
-    "mcp_login_url"
-  ],
-  "additionalProperties": false
-}