@fleetless/contracts 1.0.0

package/dist/mcp.js

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { slug } from './common.js';
+/**
+ * The MCP server of §17: **one** remote MCP endpoint for the whole platform,
+ * whose tools are the exposed services and datapoints the signed-in user's
+ * roles permit. The per-app `/mcp/<identifier>` servers this file once
+ * described were deleted by the org-central identity redesign (D5/D6).
+ *
+ * **This file describes the seam, not the protocol.** The MCP messages
+ * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
+ * Model Context Protocol and implemented with its official SDK — writing our
+ * own zod copies of them would create a second source of truth for somebody
+ * else's specification, which is the one thing this package exists to avoid.
+ * What lives here is what *Fleetless* decides: which revision we speak, where
+ * the endpoint is, how a tool is named, and what the console is shown before
+ * an end user ever connects.
+ */
+/**
+ * The protocol revision W7c speaks. Chosen with André on 2026-08-18 over the
+ * newer `2026-07-28`.
+ *
+ * This is the latest revision the **stable** MCP TypeScript SDK ships, and it
+ * negotiates down to `2024-11-05`, so it covers the AI tools that exist today.
+ * `2026-07-28` is real and is where the protocol is going — it *removes*
+ * Streamable HTTP's session ids, the standalone SSE channel and resumability,
+ * and servers speaking only it answer `405` to GET and DELETE.
+ *
+ * **Which is why this server is stateless anyway.** Building sessions we would
+ * have to delete again is work in the wrong direction, and a per-process
+ * session map is the assumption that breaks at the second cloud instance —
+ * the register already carries one row of exactly that shape
+ * (`max_realtime_connections`), and W8 is where a second instance appears.
+ */
+export const MCP_PROTOCOL_VERSION = '2025-11-25';
+/**
+ * The path of the **central** MCP server — what a *Fleetless user* pastes into
+ * their AI tool, appended to the cloud's public base URL.
+ *
+ * **Not parameterised, and that is now a statement rather than the absence of
+ * one.** The central endpoint serves the org's team with the console tool
+ * family (2026-09-05, D7); an app's users reach a different endpoint, whose
+ * path `mcpAppEndpointPath` builds. Two constants for two audiences, so a call
+ * site says which it means instead of an argument deciding it.
+ *
+ * **The canonical URL is `<PUBLIC_API_BASE_URL>${MCP_ENDPOINT_PATH}`, not the
+ * friendly alias.** `mcp.fleetless.dev` is a reverse proxy onto the same
+ * cloud, but the cloud mints every OAuth issuer, resource and `aud` from
+ * `PUBLIC_API_BASE_URL` and compares the token's `aud` against that string —
+ * never against the request's `Host`. Hand out the canonical one.
+ */
+export const MCP_ENDPOINT_PATH = '/mcp';
+/**
+ * The path of **one app's** MCP server (D7) — what an app user pastes into
+ * their AI tool, served only while the app's `appAuthConfig.mcp_enabled` is on.
+ *
+ * A helper rather than a template literal at four call sites, for
+ * `OAUTH_PATHS`' reason: the console shows this string with a copy button, the
+ * cloud registers the route from it, and the docs render it. A path spelled in
+ * three places is a path two of them will one day spell differently — and this
+ * repository has already paid for exactly that, with an `idpStart` entry naming
+ * a route the cloud had deleted.
+ *
+ * **This is the path, not the URL.** Append it to `PUBLIC_API_BASE_URL`, the
+ * canonical origin the cloud mints every issuer and audience from, rather than
+ * to the friendly `mcp.fleetless.dev` alias — a token's `aud` is compared
+ * against the canonical string and never against the request's `Host`.
+ *
+ * There was a `mcpEndpointPath(appIdentifier)` before, deleted with the per-app
+ * endpoint in the central-MCP cut and remembered here because the shape of that
+ * mistake is worth not repeating: the console kept offering a copy button for a
+ * URL that answered `404`. This one exists **with** its endpoint, and the
+ * cloud's route-manifest test is what keeps them together.
+ */
+export function mcpAppEndpointPath(appIdentifier) {
+    return `/mcp/${appIdentifier}`;
+}
+export function MCP_APP_PATHS(appIdentifier) {
+    const endpoint = mcpAppEndpointPath(appIdentifier);
+    return {
+        endpoint,
+        protectedResourceMetadata: `/.well-known/oauth-protected-resource${endpoint}`,
+        authorizationServerMetadata: `/.well-known/oauth-authorization-server${endpoint}`,
+        register: `${endpoint}/oauth/register`,
+        authorize: `${endpoint}/oauth/authorize`,
+        token: `${endpoint}/oauth/token`,
+    };
+}
+/**
+ * Which exposed kind a tool came from. Not the MCP protocol's vocabulary —
+ * ours, so the console can group a preview the way the services editor is
+ * grouped.
+ */
+export const mcpToolKind = z.enum(['datapoint', 'service', 'action', 'publisher', 'camera']);
+/** MCP's own bound on a tool name, and the charset that is safe across clients. */
+export const MCP_TOOL_NAME_MAX = 128;
+export const mcpToolNamePattern = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * One exposure of a robot, as `robot_describe` and the console's per-role
+ * preview list it (FL-006). Every exposure the role grants is listed —
+ * a missing `description` is shown as `null`, never used to hide the entry.
+ *
+ * `input_schema` is a JSON Schema document generated from an action's,
+ * service's or publisher's `parameters`; `null` for the other kinds. It is
+ * `unknown` for the same reason the retired `mcpToolPreview.input_schema`
+ * was: pinning it would mean maintaining a zod description of JSON Schema.
+ */
+export const mcpExposure = z.object({
+    slug,
+    kind: mcpToolKind,
+    description: z.string().max(2000).nullable(),
+    /** A datapoint's `numeric.unit`, verbatim; `null` for every other kind and for a unitless datapoint. */
+    unit: z.string().max(32).nullable(),
+    /**
+     * A datapoint's `numeric.decimals`, verbatim; `null` for every other kind
+     * and for a datapoint that does not set it. Required-nullable rather than
+     * optional for the same reason as `unit`: an omitted field would make a
+     * producer that forgot the datapoint's configuration indistinguishable from
+     * one reporting a datapoint that has none.
+     */
+    decimals: z.number().int().min(0).max(6).nullable(),
+    input_schema: z.unknown().nullable(),
+});
+/** The two role capabilities a robot tool can need beyond a slug grant. `presence` is a stream and has no tool. */
+export const mcpCapabilities = z.object({
+    action_history: z.boolean(),
+    assets: z.boolean(),
+});
+/** What one caller may do on one robot — the answer to `robot_describe`. */
+export const mcpRobotDatasheet = z.object({
+    robot_id: z.uuid(),
+    robot_name: z.string().min(1).max(200),
+    capabilities: mcpCapabilities,
+    exposures: z.array(mcpExposure).max(2000),
+});
+/**
+ * What a developer sees before an end user connects: the datasheet each
+ * robot of the app would answer for one role. Replaces the per-slug tool
+ * preview and its `omitted` list — with a fixed catalog there is no tool to
+ * omit, only exposures to grant.
+ */
+export const mcpRolePreviewResponse = z.object({
+    role_id: z.uuid(),
+    robots: z.array(mcpRobotDatasheet).max(500),
+});
+/**
+ * Where a signed asset link is served. An MCP session token is refused on
+ * REST by design, so `asset_get`/`urdf_get` mint a bearer-free link the agent
+ * behind the client can fetch. Lifetime is fixed; the token binds robot, asset
+ * and expiry under `JWT_SECRET`.
+ */
+export const MCP_ASSET_LINK_PATH = '/api/asset-links';
+export const MCP_ASSET_LINK_TTL_MS = 15 * 60 * 1000;

package/dist/oauth.d.ts

@@ -0,0 +1,344 @@
+import { z } from 'zod';
+/**
+ * **OAuth 2.1, and it remains only for MCP** (2026-09-05 app-user-auth, D8).
+ *
+ * This file used to describe two front doors: an app's end users signing in
+ * through a Fleetless-hosted, app-branded login page, and MCP clients signing
+ * in for the central endpoint. The first is deleted. An app now has its own UI
+ * and calls the JSON client-auth API (`client-auth.ts`); Fleetless renders an
+ * app user no page, so there is no hosted login, no consent screen, no
+ * developer-registered client and no app-level dynamic registration.
+ *
+ * What remains is the MCP authorization server — central, for Fleetless users,
+ * and per app for an app's users — and the console's own OAuth portal, which
+ * answers `oauthRedirectResponse` at its login and sign-up steps.
+ *
+ * The client model this file was written to get right is still the important
+ * part, and it survived the cut intact: an MCP client **registers itself**
+ * (RFC 7591) because the person only ever pastes a URL into an AI tool.
+ * Nobody vetted it, its redirect URIs arrive from the client itself, and the
+ * tools it will call move a physical robot. That is why consent names the
+ * client with an explicit *unverified* marker — see `clientMcpInteraction` in
+ * `client-auth.ts`, which is where the per-app half of that screen is now
+ * described, because the app renders it and Fleetless does not.
+ */
+/**
+ * **This file speaks two error dialects on purpose, and unifying them would
+ * break conformance.**
+ *
+ * The OAuth endpoints (`/mcp/oauth/authorize`, `/mcp/oauth/token`,
+ * registration) answer in RFC 6749 §5.2's shape — a flat `error` string from a fixed set,
+ * with an optional `error_description`. That is what an RFC-compliant client
+ * parses, and `mcp-inspector` is such a client. A Fleetless `apiError` there
+ * would be well-formed JSON that no standard client can read.
+ *
+ * The *management* endpoints beside them — configuring a provider, editing an
+ * app's auth settings — are ordinary console API and use `apiError` with
+ * `ERROR_CODES` like everything else.
+ *
+ * So: **two shapes, split by audience, not by accident.** Written down here
+ * because the natural instinct on finding two error formats in one server is
+ * to unify them, and doing so silently removes the reason the standard one is
+ * there.
+ *
+ * **The split is by audience and the path prefix will mislead you.**
+ * `/mcp/oauth/consent` sits under an `/oauth/` segment and is nevertheless an
+ * `apiError` endpoint: it is not in RFC 6749's or RFC 7591's endpoint set, and
+ * its only caller is a page this server rendered. Whoever later sorts these by
+ * prefix will move it, and be wrong. Ask who parses the response, not where it
+ * lives.
+ */
+export declare const oauthErrorCode: z.ZodEnum<{
+    invalid_request: "invalid_request";
+    invalid_client: "invalid_client";
+    invalid_grant: "invalid_grant";
+    unauthorized_client: "unauthorized_client";
+    unsupported_grant_type: "unsupported_grant_type";
+    invalid_scope: "invalid_scope";
+    access_denied: "access_denied";
+    server_error: "server_error";
+    temporarily_unavailable: "temporarily_unavailable";
+    invalid_target: "invalid_target";
+}>;
+export type OauthErrorCode = z.infer<typeof oauthErrorCode>;
+export declare const oauthError: z.ZodObject<{
+    error: z.ZodEnum<{
+        invalid_request: "invalid_request";
+        invalid_client: "invalid_client";
+        invalid_grant: "invalid_grant";
+        unauthorized_client: "unauthorized_client";
+        unsupported_grant_type: "unsupported_grant_type";
+        invalid_scope: "invalid_scope";
+        access_denied: "access_denied";
+        server_error: "server_error";
+        temporarily_unavailable: "temporarily_unavailable";
+        invalid_target: "invalid_target";
+    }>;
+    error_description: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    fleetless_code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OauthError = z.infer<typeof oauthError>;
+/**
+ * A redirect URI, and the rule is stricter than "a URL".
+ *
+ * **The defence for this was already written down in this codebase, twice.**
+ * `config.ts` validates a V4L2 device path from the wire with a prefix rule
+ * *and* an explicit refusal of `..` segments, tested, with the reasoning
+ * recorded; W7's review then found a `package://` traversal in the bridge
+ * that the same rule would have prevented, and the finding that mattered was
+ * not the traversal but that **the rule existed one file over and was never
+ * carried across.** A redirect URI is the same shape of problem from a less
+ * trusted source: an attacker-supplied string that decides where a credential
+ * is sent.
+ *
+ * Matching at the server is **exact string comparison against a registered
+ * value** — never a prefix, never a wildcard host, never "starts with". A
+ * prefix match on `https://app.example.com/cb` accepts
+ * `https://app.example.com/cb.evil.test`.
+ */
+export declare const redirectUri: z.ZodString;
+export type RedirectUri = z.infer<typeof redirectUri>;
+/**
+ * OAuth 2.1 removes the implicit and password grants and **makes PKCE
+ * mandatory for every client**, public or confidential. `plain` is not
+ * offered: a challenge equal to its verifier defends against nothing, and
+ * offering it means a downgrade is negotiable.
+ */
+export declare const codeChallengeMethod: z.ZodEnum<{
+    S256: "S256";
+}>;
+/**
+ * **How many callbacks one dynamic registration may name.**
+ *
+ * RFC 7591 lets a client register several; five is above every real MCP client
+ * observed and far below "a place to store data" on an endpoint that takes no
+ * credential. It lives here rather than in the cloud because this schema now
+ * *publishes* the bound: a number the reference states and a different number
+ * the server enforces is two policies for one decision, and the endpoint spent
+ * a release documenting `20` while refusing the sixth URI.
+ */
+export declare const MCP_DCR_MAX_REDIRECT_URIS = 5;
+/**
+ * RFC 7591 dynamic client registration — **the metadata both MCP
+ * authorization servers understand**, central and per-app.
+ *
+ * **Not `.strict()`, and that is the schema agreeing with the server rather
+ * than a gap in it.** §3.1 obliges a registration endpoint to ignore metadata
+ * it does not understand, and real MCP clients send `client_uri`, `logo_uri`,
+ * `software_id` and `contacts`. A strict shape here would describe a `400`
+ * that no conforming client ever earns, and would take the whole
+ * paste-the-URL flow down if anything ever parsed against it. Unknown keys
+ * are therefore stripped by this schema and ignored by the server, which is
+ * the same answer said twice.
+ *
+ * **The server still reads the body field by field** (`registerMcpDynamicClient`
+ * in `cloud/src/mcp-oauth-core.ts`), and the reason is the error vocabulary,
+ * not the shape: §3.2.2 distinguishes `invalid_redirect_uri` from
+ * `invalid_client_metadata`, and one `safeParse` failure cannot say which of
+ * the two a caller earned. So this schema is what the endpoint *accepts*, and
+ * the handler is what turns a miss into the right RFC code.
+ *
+ * **`client_name` is optional because the server treats it as optional**: RFC
+ * 7591 makes every metadata field optional, and a registration that omits it
+ * is recorded under a default name rather than refused. `redirect_uris` is the
+ * one field a registration cannot do without — there is nowhere to return a
+ * code otherwise.
+ */
+export declare const dynamicClientRegistrationRequest: z.ZodObject<{
+    redirect_uris: z.ZodArray<z.ZodString>;
+    client_name: z.ZodOptional<z.ZodString>;
+    token_endpoint_auth_method: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+    }>>;
+    grant_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        refresh_token: "refresh_token";
+        authorization_code: "authorization_code";
+    }>>>;
+    response_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        code: "code";
+    }>>>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DynamicClientRegistrationRequest = z.infer<typeof dynamicClientRegistrationRequest>;
+export declare const dynamicClientRegistrationResponse: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodString;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    grant_types: z.ZodArray<z.ZodString>;
+    response_types: z.ZodArray<z.ZodString>;
+    token_endpoint_auth_method: z.ZodLiteral<"none">;
+    client_id_issued_at: z.ZodNumber;
+    client_secret_expires_at: z.ZodLiteral<0>;
+}, z.core.$strip>;
+export type DynamicClientRegistrationResponse = z.infer<typeof dynamicClientRegistrationResponse>;
+/**
+ * **The MCP token endpoint's request — one grant, because the servers serve
+ * one.**
+ *
+ * Both authorization servers, central and per-app, exchange through
+ * `exchangeMcpAuthorizationCode` (`cloud/src/mcp-oauth-core.ts`), whose first
+ * act is to refuse anything but `authorization_code` before a single lookup
+ * happens. There is no refresh grant here: a session ends when its token
+ * expires and the client signs in again.
+ *
+ * **This was a `discriminatedUnion` with a `refresh_token` branch, and that
+ * branch had no producer left.** It described the app-level OAuth surface,
+ * which is deleted; an app user's refresh runs through `POST
+ * /api/client/refresh` and `refreshRequest`, a different wire on a different
+ * route. Keeping it would have published, to every MCP client author reading
+ * `/openapi.json`, a grant the endpoint answers `unsupported_grant_type` to.
+ * The argument the branch carried is worth keeping even though the branch is
+ * not: **RFC 8707's `resource` has to survive rotation**, because a refresh
+ * that drops the audience mints a successor with no `aud`, and the validating
+ * resource then refuses a token the caller obtained legitimately — one token
+ * lifetime after a login that worked, to somebody who did nothing wrong. If a
+ * refresh grant is ever added here, it carries `resource`.
+ *
+ * `code_verifier`'s bounds are RFC 7636 §4.1's, charset included. A verifier
+ * is compared, not parsed, so a length nobody checks is a length an attacker
+ * chooses.
+ *
+ * **Deliberately not `.strict()`**, unlike a registration request: that comes
+ * from a client we are about to trust, where an unknown key is a caller
+ * assuming a feature into existence, while a token request comes from any
+ * RFC-compliant client, which may legitimately send parameters this server
+ * does not read. Refusing those would be a conformance bug. The consequence
+ * is worth stating because it bit the test for this very schema: unknown keys
+ * are **stripped**, so `safeParse().success` cannot tell a present field from
+ * an absent one. Assert on the parsed value.
+ */
+export declare const oauthTokenRequest: z.ZodObject<{
+    grant_type: z.ZodLiteral<"authorization_code">;
+    code: z.ZodString;
+    redirect_uri: z.ZodString;
+    client_id: z.ZodString;
+    code_verifier: z.ZodString;
+    resource: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export type OauthTokenRequest = z.infer<typeof oauthTokenRequest>;
+/**
+ * RFC 6749 §5.1's success envelope — **the second deliberate dialect, and this
+ * one is a success shape rather than an error shape.**
+ *
+ * The values inside are the same tokens `/api/client/login` mints; only the
+ * envelope differs, because an RFC-compliant client parses this one and knows
+ * nothing about Fleetless. So a consumer holding this **normalises it into
+ * `sessionTokens` and stores that** — it does not carry the envelope around.
+ * Written here rather than invented once in the cloud and once in the SDK,
+ * which is how two implementations of one wire shape start disagreeing.
+ *
+ * `token_type` is `Bearer` as a literal because it is what this server emits.
+ * RFC 6749 §5.1 makes the value case-insensitive **for a client reading it**;
+ * that leniency belongs in a parser we do not own, not in the shape we
+ * produce.
+ */
+export declare const oauthTokenResponse: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    expires_in: z.ZodNumber;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OauthTokenResponse = z.infer<typeof oauthTokenResponse>;
+/** RFC 8414 §2 — the document a client reads *instead of* being told anything. */
+export declare const authorizationServerMetadata: z.ZodObject<{
+    issuer: z.ZodURL;
+    authorization_endpoint: z.ZodURL;
+    token_endpoint: z.ZodURL;
+    registration_endpoint: z.ZodOptional<z.ZodURL>;
+    response_types_supported: z.ZodArray<z.ZodLiteral<"code">>;
+    grant_types_supported: z.ZodArray<z.ZodEnum<{
+        refresh_token: "refresh_token";
+        authorization_code: "authorization_code";
+    }>>;
+    code_challenge_methods_supported: z.ZodArray<z.ZodEnum<{
+        S256: "S256";
+    }>>;
+    token_endpoint_auth_methods_supported: z.ZodArray<z.ZodLiteral<"none">>;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AuthorizationServerMetadata = z.infer<typeof authorizationServerMetadata>;
+/**
+ * RFC 9728 — what a *resource* publishes about who may authorize for it.
+ *
+ * W7b mints tokens bound to a resource that W7c builds. **A minting mechanism
+ * with no validator is the failure mode this project has now met twelve times
+ * in one wave: a check that cannot fail.** So W7b also ships a resource that
+ * *rejects* a token whose audience names something else, and the gate measures
+ * the rejection rather than the presence of the claim.
+ */
+export declare const protectedResourceMetadata: z.ZodObject<{
+    resource: z.ZodURL;
+    authorization_servers: z.ZodArray<z.ZodURL>;
+    bearer_methods_supported: z.ZodArray<z.ZodLiteral<"header">>;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ProtectedResourceMetadata = z.infer<typeof protectedResourceMetadata>;
+/**
+ * Where the page goes next, and this shape is a **redirect the server chose**,
+ * never one the page may be talked into.
+ *
+ * The server emits exactly two kinds of value here: its own consent path, or a
+ * redirect URI already registered for this client with the code appended.
+ * A page must navigate to it and nothing else — in particular it must not fall
+ * back to any URL that arrived in its own query string if this field is
+ * missing, which is how an open redirect gets built by accident on the way to
+ * handling an error.
+ *
+ * JSON rather than a `302` because the page is an application: a redirect
+ * cannot carry a field-level credential error back to a form, and a flow that
+ * answers errors by navigating loses the state the user typed.
+ */
+export declare const oauthRedirectResponse: z.ZodObject<{
+    redirect_to: z.ZodString;
+}, z.core.$strip>;
+export type OauthRedirectResponse = z.infer<typeof oauthRedirectResponse>;
+/**
+ * The authorization request of RFC 6749 §4.1.1 with PKCE (RFC 7636) — the
+ * shape `/mcp/oauth/authorize` reads.
+ *
+ * **The cloud reads every parameter by hand, and that is not an omission** —
+ * each failure has its own answer. `client_id` and `redirect_uri` are refused
+ * flat, with no redirect, because until both are confirmed there is no trusted
+ * target to bounce a browser to; everything after them is reported to the
+ * client's own callback as query parameters. A single `safeParse` would
+ * collapse those two answers into one. So this schema pins the successful
+ * shape and the documentation, not the error path.
+ *
+ * **Four route entries point at it**: `GET /mcp/oauth/authorize` and
+ * `GET /mcp/:appIdentifier/oauth/authorize` (D7), which read the same wire.
+ * They spent a release naming nothing — the app-level `/oauth/authorize` this
+ * was written for was deleted, and `query: null` was read as "there is no
+ * query here" rather than as "the handler reads it by hand" — and the eight
+ * documented parameters left `/openapi.json` with nothing able to notice,
+ * because the undocumented-field ratchet counts gaps and a fully documented
+ * schema leaving makes that number improve.
+ */
+export declare const oauthAuthorizeQuery: z.ZodObject<{
+    response_type: z.ZodLiteral<"code">;
+    client_id: z.ZodString;
+    redirect_uri: z.ZodString;
+    code_challenge: z.ZodString;
+    code_challenge_method: z.ZodLiteral<"S256">;
+    state: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OauthAuthorizeQuery = z.infer<typeof oauthAuthorizeQuery>;
+/**
+ * **`oauthRegisterQuery` is deleted, and this note is what it leaves behind.**
+ *
+ * It carried one parameter, `app_identifier`, on the argument that RFC 7591's
+ * registration body has no field for it and one endpoint could serve every
+ * app. It was kept — explicitly, in its own doc comment — "for the per-app MCP
+ * registration the MCP train adds (D7), which needs exactly this parameter".
+ *
+ * **That train shipped and needed no such parameter.** `POST
+ * /mcp/:appIdentifier/oauth/register` puts the app in the **path**, built by
+ * `MCP_APP_PATHS`, and `resolveAppMcpTarget` reads it from `request.params`;
+ * `registerMcpDynamicClient` never looks at a query at all. So the one reason
+ * the schema was kept became false the moment its successor arrived, and
+ * nothing was watching the reason — which is the failure this comment is here
+ * to make expensive to repeat. A schema reserved for a future route is a claim
+ * with an expiry date on it, and the expiry has to be checked by somebody.
+ */