@fleetless/contracts 1.1.0 → 2.0.0

package/dist/oauth.js

@@ -188,7 +188,7 @@ export const dynamicClientRegistrationRequest = z
         description: '`none`, RFC 7591\'s value for a public client, and the only value either server registers. Any other value is **refused rather than silently downgraded**: a client that believes it holds a secret and does not has a wrong mental model of its own security. There is no client secret to hold — mandatory PKCE (`S256`) is the defence.',
     }),
     grant_types: z.array(z.enum(['authorization_code', 'refresh_token'])).optional().meta({
-        description: 'Accepted for conformance with RFC 7591 and then **ignored**. What comes back is what was actually granted, which §3.2.1 permits a server to substitute: `authorization_code` and nothing else, so a client that asks for `refresh_token` is registered and told plainly that it did not get one.',
+        description: 'Accepted for conformance with RFC 7591 and then **ignored**: both MCP authorization servers grant `authorization_code` and `refresh_token` to every registration, and the answer states what was granted (§3.2.1) rather than what was asked.',
     }),
     response_types: z.array(z.enum(['code'])).optional().meta({
         description: 'Accepted for conformance and then **ignored**; the response names `code`, which is the only response type OAuth 2.1 leaves, the implicit grant having been removed.',
@@ -211,7 +211,7 @@ export const dynamicClientRegistrationResponse = z.object({
         description: 'The redirect URIs this registration was accepted for. A code is returned to one of these and nowhere else.',
     }),
     grant_types: z.array(z.string()).meta({
-        description: 'The grants this client may use. Always exactly `["authorization_code"]` — a client that asked for `refresh_token` is registered and told here that it did not get one, which is the substitution RFC 7591 §3.2.1 permits.',
+        description: 'The grants this client may use. Always exactly `["authorization_code", "refresh_token"]` — an exchange mints a refresh token and the token endpoint rotates it.',
     }),
     response_types: z.array(z.string()).meta({
         description: 'The response types this client may ask for: `code`.',
@@ -227,26 +227,20 @@ export const dynamicClientRegistrationResponse = z.object({
     }),
 });
 /**
- * **The MCP token endpoint's request — one grant, because the servers serve
- * one.**
+ * **The MCP token endpoint's request — two grants, one per half of a
+ * session.**
  *
- * Both authorization servers, central and per-app, exchange through one
- * implementation, 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.
+ * `authorization_code` mints the first access token and a refresh token;
+ * `refresh_token` rotates that refresh token into a new pair. Both MCP
+ * authorization servers, central and per-app, answer both; the console's own
+ * OAuth portal answers the code grant only.
  *
- * **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`.
+ * **RFC 8707's `resource` has to survive rotation**: a refresh that drops the
+ * audience mints a successor with no `aud`, and the validating resource then
+ * refuses a token the caller obtained legitimately. So the server keeps the
+ * audience on the refresh token's own row, and a `resource` named here must
+ * match it or the answer is `invalid_target` — before the token is consumed,
+ * so a typo costs nothing.
  *
  * `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
@@ -260,10 +254,10 @@ export const dynamicClientRegistrationResponse = z.object({
  * **stripped**, which bit the test for this schema: `safeParse().success`
  * cannot tell a present field from an absent one. Assert on the parsed value.
  */
-export const oauthTokenRequest = z
+export const oauthCodeTokenRequest = z
     .object({
     grant_type: z.literal('authorization_code').meta({
-        description: 'Always `authorization_code`: this request exchanges the code from the authorize redirect for tokens. Any other value — `refresh_token` included — is `unsupported_grant_type`, refused before the code is looked up.',
+        description: '`authorization_code`: this request exchanges the code from the authorize redirect for an access token and a refresh token.',
     }),
     code: z.string().min(1).max(500).meta({
         description: 'The authorization code from the redirect. It may be exchanged once; a second presentation is `invalid_grant`, the same answer a fabricated code gets.',
@@ -284,6 +278,27 @@ export const oauthTokenRequest = z
     .meta({
     description: "RFC 6749 §4.1.3's authorization-code exchange with PKCE, as either MCP authorization server reads it. Sent as `application/x-www-form-urlencoded`, per §4.1.3, though the server accepts a JSON body too.",
 });
+export const oauthRefreshTokenRequest = z
+    .object({
+    grant_type: z.literal('refresh_token').meta({
+        description: '`refresh_token`: this request rotates a refresh token into a new access token and a new refresh token. The presented token is consumed; presenting it again revokes the whole session.',
+    }),
+    refresh_token: z.string().min(1).max(500).meta({
+        description: 'The refresh token from the last token response. Bound to the client that received it and to one identity space: presented by another client, or at the other MCP server, it is `invalid_grant` and stays unconsumed.',
+    }),
+    client_id: z.string().min(1).max(200).meta({
+        description: 'The client the refresh token was issued to, as registered. A refresh token is not transferable between clients.',
+    }),
+    resource: z.url().optional().meta({
+        description: 'The resource the new token is for, per RFC 8707. Optional; when named it must be the audience the session was issued for, or the answer is `invalid_target` and the refresh token is left untouched. The successor carries the same audience either way.',
+    }),
+})
+    .meta({
+    description: "RFC 6749 §6's refresh, as either MCP authorization server reads it. Every use rotates: the answer carries a new refresh token and the presented one is dead.",
+});
+export const oauthTokenRequest = z.discriminatedUnion('grant_type', [oauthCodeTokenRequest, oauthRefreshTokenRequest]).meta({
+    description: 'What an MCP token endpoint accepts: the authorization-code exchange, or a refresh. Any other `grant_type` is `unsupported_grant_type`, refused before a lookup happens.',
+});
 /**
  * RFC 6749 §5.1's success envelope — **the second deliberate dialect, and this
  * one is a success shape rather than an error shape.**
@@ -311,7 +326,7 @@ export const oauthTokenResponse = z.object({
         description: 'How long the access token is valid, in **seconds**, per RFC 6749 §5.1. Not a timestamp, and not milliseconds.',
     }),
     refresh_token: z.string().min(1).optional().meta({
-        description: 'The refresh token, when one was issued. It rotates on every use.',
+        description: 'The refresh token. Both MCP token endpoints issue one on every exchange and every refresh; it rotates on every use, lives ninety days from its last use, and dies with the account\'s sessions — a block, a password change, a withdrawn consent. The console\'s own OAuth portal issues none.',
     }),
     scope: z.string().max(500).optional().meta({
         description: 'The scopes the issued token actually carries, space-separated.',
@@ -335,7 +350,7 @@ export const authorizationServerMetadata = z.object({
         description: 'The response types this server offers: `code` only, the implicit grant being gone with OAuth 2.1.',
     }),
     grant_types_supported: z.array(z.enum(['authorization_code', 'refresh_token'])).meta({
-        description: 'The grants this server offers. OAuth 2.1 removes the implicit and password grants, so neither appears here.',
+        description: 'The grants this server offers: `authorization_code` and `refresh_token`. OAuth 2.1 removes the implicit and password grants, so neither appears here.',
     }),
     code_challenge_methods_supported: z.array(codeChallengeMethod).meta({
         description: 'The PKCE challenge methods accepted: `S256` only. `plain` is not offered — a challenge equal to its verifier defends against nothing, and offering it would make a downgrade negotiable.',

package/dist/protocol.d.ts

@@ -1,18 +1,67 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Bridge <-> cloud protocol, version 2.
+ * Bridge <-> cloud protocol, version 3.
  *
- * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge: `protocol_mismatch`, which names both versions and
- * reaches the robot's detail view as `last_hello_error`.
+ * The version is exchanged in the hello handshake. Since 2026-09 the cloud
+ * serves a **window** of versions, not one: every entry of
+ * `PROTOCOL_VERSIONS` whose sunset has not passed. A version is deprecated
+ * by the cloud release that supersedes it and sunset `PROTOCOL_SUNSET_DAYS`
+ * later. Outside the window the cloud refuses with `protocol_mismatch`,
+ * which names the window and reaches the robot's detail view as
+ * `last_hello_error`.
+ *
+ * **3 (2026-09-22):** the ping carries `latency_ms` and `lag_ms`, the bridge
+ * sends `link_mode`, `bridge_state` gains `low_bandwidth`, and the
+ * `bridge_pressure` datapoint is gone. A protocol-2 bridge is served until
+ * its sunset, and the cloud's protocol-2 adapter owes it two translations on
+ * the way in: it drops its pressure datapoints, and it rewrites an
+ * `asset_progress` failure of kind `too_large` — a kind protocol 3 no longer
+ * has — to `refused` with `details: null`, because a 2.0.0 `bridgeAssetProgress`
+ * refuses the frame outright otherwise.
  *
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
- * beside `message`. The check is `!==`, not a floor, so a bridge that is not
- * exactly this version is refused entirely. That is deliberate: a cloud and a
- * bridge that disagree about the wire should not pretend otherwise.
+ * beside `message`.
+ */
+export declare const PROTOCOL_VERSION = 3;
+/** Days between a version's deprecation and its sunset. */
+export declare const PROTOCOL_SUNSET_DAYS = 90;
+export interface ProtocolVersionEntry {
+    version: number;
+    /** The first bridge package version that speaks this protocol. */
+    bridge_from: string;
+    /** ISO date of the cloud release that superseded it; null while current. */
+    deprecated_at: string | null;
+}
+/**
+ * Every protocol version the cloud has served, oldest first. A test keeps
+ * exactly one entry current and equal to `PROTOCOL_VERSION`; `test/changelog.test.ts`
+ * requires the CHANGELOG's current section to name the newest `bridge_from`
+ * and the previous entry's `sunsetOf(...)` date, and `scripts/verify-version-tag.mjs`
+ * requires a dated heading for the tag being released.
  */
-export declare const PROTOCOL_VERSION = 2;
+export declare const PROTOCOL_VERSIONS: readonly ProtocolVersionEntry[];
+/** The newest bridge package. The cloud mails organisations still below it. */
+export declare const LATEST_BRIDGE_VERSION = "4.0.0";
+export interface ProtocolStatus {
+    status: 'current' | 'deprecated' | 'unsupported';
+    /** ISO date, or null for a current or unknown version. */
+    sunset_at: string | null;
+}
+export declare function sunsetOf(entry: ProtocolVersionEntry): string | null;
+/**
+ * The window rule itself: `protocolStatus` and `minimumProtocolVersion` are
+ * this function over `PROTOCOL_VERSIONS`, and the cloud calls it directly.
+ *
+ * The table is a parameter because callers pass one with a deprecated entry —
+ * tests, and any caller reasoning about a sunset. The real table has none
+ * until the first bump, so a hard-coded `PROTOCOL_VERSIONS` would leave the
+ * deprecated and unsupported branches unreachable.
+ */
+export declare function statusFromTable(table: readonly ProtocolVersionEntry[], version: number, today: Date): ProtocolStatus;
+export declare function protocolStatus(version: number, today?: Date): ProtocolStatus;
+/** The lowest version still inside its window today. */
+export declare function minimumProtocolVersion(today?: Date): number;
 /**
  * The bridge socket close code for "this robot no longer exists".
  *
@@ -24,6 +73,20 @@ export declare const PROTOCOL_VERSION = 2;
  * more informative than "connection closed".
  */
 export declare const CLOSE_ROBOT_DELETED = 4004;
+/**
+ * The bridge socket close code for "the token you connected with is gone".
+ *
+ * The cloud closes a robot's live socket with this after the robot's token was
+ * rotated. A 4.0.0 bridge reads it the way it reads `invalid_token` — stop,
+ * exit 2 — because the secret it holds is no longer a secret anyone accepts,
+ * and no amount of reconnecting produces the new one. A 3.x bridge does not
+ * know the code, reconnects, and is refused at hello; that ends the same way,
+ * one round trip later.
+ *
+ * Its own code rather than `CLOSE_ROBOT_DELETED`, which would tell an operator
+ * their robot had been deleted when it very much still exists.
+ */
+export declare const CLOSE_TOKEN_ROTATED = 4005;
 /**
  * How long a command waits for its answer when the caller names no patience
  * of its own.
@@ -113,10 +176,26 @@ export declare const bridgeHello: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type BridgeHello = z.infer<typeof bridgeHello>;
-/** Cloud accepts the bridge: the robot is online from here on. */
+/**
+ * Cloud accepts the bridge: the robot is online from here on.
+ *
+ * `protocol` and `bridge` are optional so that a bridge parsing `hello_ok`
+ * strictly still parses one from an older cloud. `status` here is never
+ * `unsupported`: an unsupported version gets `hello_error`, not this frame.
+ */
 export declare const cloudHelloOk: z.ZodObject<{
     type: z.ZodLiteral<"hello_ok">;
     robot_id: z.ZodUUID;
+    protocol: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            deprecated: "deprecated";
+            current: "current";
+        }>;
+        sunset_at: z.ZodNullable<z.ZodISODate>;
+    }, z.core.$strip>>;
+    bridge: z.ZodOptional<z.ZodObject<{
+        latest_version: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CloudHelloOk = z.infer<typeof cloudHelloOk>;
 /** Cloud refuses the bridge (bad token, incompatible protocol, ...). */
@@ -129,22 +208,40 @@ export type CloudHelloError = z.infer<typeof cloudHelloError>;
 /**
  * One datapoint sample. `timestamp_ms` is the capture time at the bridge —
  * never the receive time — so clients compute age themselves.
+ *
+ * Which is exactly why `backfill` has to be on the frame. A replayed sample
+ * carries the capture time it had during the outage, so a cloud that measures
+ * lag from every arriving frame reads a two-hour disconnect as two hours of
+ * lag the moment the bridge reconnects — and reports a healthy link as the
+ * worst one it has ever seen. Only the bridge knows which frames came out of
+ * its buffer, so only the bridge can say.
  */
 export declare const datapointFrame: z.ZodObject<{
     type: z.ZodLiteral<"datapoint">;
     slug: z.ZodString;
     value: z.ZodUnknown;
     timestamp_ms: z.ZodNumber;
+    backfill: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type DatapointFrame = z.infer<typeof datapointFrame>;
 /**
  * Latency probe, cloud → bridge. The cloud sends its own clock in `ts_ms`;
  * the bridge echoes it back untouched and the cloud derives the round-trip
  * latency shown as `bridge_state.latency_ms`.
+ *
+ * Sent every `pingIntervalMs`; the bridge answers with `pong`. Since protocol
+ * 3 it also carries what the cloud measured about this link, so the bridge
+ * can decide on its low-bandwidth mode with an end-to-end number: the
+ * round trip of the last pong, and the datapoint lag — the median over the
+ * last five seconds of (receive time − `timestamp_ms`) minus the minimum of
+ * the last ten minutes, which cancels the robot's clock offset. `null` until
+ * the cloud has a sample. A protocol-2 bridge reads only `ts_ms`.
  */
 export declare const cloudPing: z.ZodObject<{
     type: z.ZodLiteral<"ping">;
     ts_ms: z.ZodNumber;
+    latency_ms: z.ZodNullable<z.ZodNumber>;
+    lag_ms: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 export type CloudPing = z.infer<typeof cloudPing>;
 /** Immediate bridge answer to a `CloudPing`, `ts_ms` echoed unchanged. */
@@ -153,6 +250,24 @@ export declare const bridgePong: z.ZodObject<{
     ts_ms: z.ZodNumber;
 }, z.core.$strip>;
 export type BridgePong = z.infer<typeof bridgePong>;
+/**
+ * The bridge's low-bandwidth mode changed. Sent on every transition and once
+ * after `hello_ok`, at tier 0 like the pong: the cloud folds it into
+ * `bridge_state.low_bandwidth`, and a frame that waited behind bulk would
+ * describe a state that is already over.
+ */
+export declare const bridgeLinkMode: z.ZodObject<{
+    type: z.ZodLiteral<"link_mode">;
+    low_bandwidth: z.ZodBoolean;
+    reason: z.ZodEnum<{
+        lag: "lag";
+        dwell: "dwell";
+        forced: "forced";
+        recovered: "recovered";
+    }>;
+    at_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type BridgeLinkMode = z.infer<typeof bridgeLinkMode>;
 /**
  * The published configuration, cloud → bridge — the bridge applies the
  * published version. Sent right after `hello_ok` and again on every publish,
@@ -191,6 +306,7 @@ export declare const cloudConfig: z.ZodObject<{
             type: z.ZodString;
             field: z.ZodOptional<z.ZodString>;
             rate_throttle_hz: z.ZodOptional<z.ZodNumber>;
+            low_bandwidth: z.ZodOptional<z.ZodLiteral<"keep">>;
             description: z.ZodOptional<z.ZodString>;
             numeric: z.ZodOptional<z.ZodObject<{
                 scale: z.ZodOptional<z.ZodNumber>;
@@ -357,6 +473,23 @@ export declare const cloudConfig: z.ZodObject<{
             snapshot_interval_seconds: z.ZodNumber;
             description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
+        low_bandwidth: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                on: "on";
+                off: "off";
+            }>>;
+            enter_lag_ms: z.ZodOptional<z.ZodNumber>;
+            enter_after_s: z.ZodOptional<z.ZodNumber>;
+            exit_lag_ms: z.ZodOptional<z.ZodNumber>;
+            exit_after_s: z.ZodOptional<z.ZodNumber>;
+            datapoint_max_hz: z.ZodOptional<z.ZodNumber>;
+            camera: z.ZodOptional<z.ZodEnum<{
+                reduce: "reduce";
+                stop: "stop";
+            }>>;
+            camera_bitrate_kbps: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strip>;
 export type CloudConfig = z.infer<typeof cloudConfig>;
@@ -377,6 +510,7 @@ export declare const bridgeConfigApplied: z.ZodObject<{
             service: "service";
             publisher: "publisher";
             camera: "camera";
+            low_bandwidth: "low_bandwidth";
         }>;
         code: z.ZodString;
         message: z.ZodString;
@@ -538,72 +672,17 @@ export type BridgeTypeDefinitions = z.infer<typeof bridgeTypeDefinitions>;
 /**
  * The built-in `bridge_state` datapoint every robot has: connection status
  * plus latency, the basis for offline-aware client UIs.
+ *
+ * `online` and `latency_ms` are cloud-observed (the socket, the pong);
+ * `low_bandwidth` is bridge-reported through `link_mode` and `false` for a
+ * bridge that never sends one.
  */
 export declare const bridgeState: z.ZodObject<{
     online: z.ZodBoolean;
     latency_ms: z.ZodNullable<z.ZodNumber>;
+    low_bandwidth: z.ZodBoolean;
 }, z.core.$strip>;
 export type BridgeState = z.infer<typeof bridgeState>;
-/**
- * The built-in `bridge_pressure` datapoint: the bridge's own
- * bandwidth-shaping state, sent on the same reserved-slug path as
- * `bridge_state` so history, realtime, REST and MCP exposure fall out of the
- * ordinary datapoint machinery for free.
- */
-export declare const bridgePressure: z.ZodObject<{
-    link: z.ZodObject<{
-        rate_bps: z.ZodNullable<z.ZodNumber>;
-        snapshot_max_bytes: z.ZodNumber;
-    }, z.core.$strip>;
-    tiers: z.ZodObject<{
-        '0': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '1': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '2': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '3': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '4': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '5': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-    }, z.core.$strict>;
-    video: z.ZodObject<{
-        active_streams: z.ZodNumber;
-        bitrate_sum_kbps: z.ZodNumber;
-        uplink_kbps: z.ZodNullable<z.ZodNumber>;
-        override_kbps: z.ZodNullable<z.ZodNumber>;
-        video_budget_kbps: z.ZodNullable<z.ZodNumber>;
-        reserve_kbps: z.ZodNumber;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export type BridgePressure = z.infer<typeof bridgePressure>;
-export declare const PRESSURE_SLUG: "bridge_pressure";
 /**
  * The header of a **binary** snapshot frame, bridge → cloud.
  *
@@ -724,10 +803,10 @@ export declare const bridgeAssetProgress: z.ZodObject<{
             unresolvable: "unresolvable";
             upload_failed: "upload_failed";
             refused: "refused";
-            too_large: "too_large";
         }>;
         details: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-            limit_bytes: z.ZodNumber;
+            store_bytes: z.ZodNumber;
+            used_bytes: z.ZodNumber;
             size_bytes: z.ZodNumber;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;