@fleetless/sdk 2.1.0 → 3.0.0

package/dist/index.d.ts

@@ -18,9 +18,9 @@ import { z } from 'zod';
  *    admits it lost track.
  */
 declare const jobState: z.ZodEnum<{
+    failed: "failed";
     running: "running";
     succeeded: "succeeded";
-    failed: "failed";
     cancelled: "cancelled";
     lost: "lost";
 }>;
@@ -30,9 +30,9 @@ declare const job: z.ZodObject<{
     robot_id: z.ZodUUID;
     slug: z.ZodString;
     state: z.ZodEnum<{
+        failed: "failed";
         running: "running";
         succeeded: "succeeded";
-        failed: "failed";
         cancelled: "cancelled";
         lost: "lost";
     }>;
@@ -65,9 +65,9 @@ declare const jobEvent: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            failed: "failed";
             running: "running";
             succeeded: "succeeded";
-            failed: "failed";
             cancelled: "cancelled";
             lost: "lost";
         }>;
@@ -97,9 +97,9 @@ declare const busyDetails: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            failed: "failed";
             running: "running";
             succeeded: "succeeded";
-            failed: "failed";
             cancelled: "cancelled";
             lost: "lost";
         }>;
@@ -256,6 +256,9 @@ type DatapointEvent = z.infer<typeof datapointEvent>;
  * Access plus refresh (spec §3.4). The access token is short-lived; the
  * refresh token rotates on every use, so a stolen one is detectable when the
  * original is presented again.
+ *
+ * One shape for both identity spaces: a session is a session, and the claims
+ * inside the token are what differ.
  */
 declare const sessionTokens: z.ZodObject<{
     access_token: z.ZodString;
@@ -265,105 +268,149 @@ declare const sessionTokens: z.ZodObject<{
 type SessionTokens = z.infer<typeof sessionTokens>;
 
 /**
- * **What logout can and cannot end, said in three separable facts (W9c,
- * DEF-098).**
+ * **Why a federated sign-in ended without a session, in a code the app can
+ * branch on** — carried back to the app's own `redirect_uri` as `error`, not
+ * rendered by Fleetless (D2). The only Fleetless-rendered page in this flow is
+ * the one for a state that can no longer be resolved to a redirect URI, because
+ * then there is nowhere to send the answer.
+ *
+ * The five rows of D4's table are the first five values plus `no_access`:
  *
- * Until now this route answered `204`: the Fleetless session was over and the
- * response had nothing to say about the *other* session. For a federated user
- * that is the larger half — they clicked "log out", the IdP's cookie survived,
- * and the next login goes straight through without a password. The register
- * row calls that an expectation gap, and it is: the word on the button is
- * "log out", not "log out of this app".
+ * - `no_access` — the identity is unknown and nothing admits it, or the account
+ *   it names is not `active`. **One code for both**, because to the person the
+ *   remedy is the same — ask somebody to let you in — and a code that split an
+ *   outcome nobody acts on differently would tell a stranger which half applied.
+ * - `email_taken` — the address already belongs to another app user, and the
+ *   provider is not permitted to link (`link_verified_emails`, or the provider
+ *   did not assert `email_verified`). Deliberately not `no_access`: the remedy
+ *   is different — *sign in the way you signed up*.
+ * - `email_unverified` — the provider asserted an address without
+ *   `email_verified`. **An unverified address never produces or links an
+ *   account**, whatever the rest of the policy says.
+ * - `domain_not_allowed`, `registration_closed` — the self-registration policy
+ *   refused. Honest, because neither is about whether a person exists.
+ * - `idp_unavailable`, `exchange_failed`, `claims_incomplete`,
+ *   `provider_misconfigured`, `provider_disabled` — the provider's or the
+ *   developer's to fix, and the app can say so.
+ * - `invalid_request` — the start parameters did not hold up.
+ * - `quota_exceeded` — the org has as many app users as its `max_end_users`
+ *   quota allows, so no account can be created for this identity. Named rather
+ *   than folded into `no_access`, for `domain_not_allowed`'s reason: it is not
+ *   about the person, the app can say what happened, and the remedy belongs to
+ *   the developer rather than to whoever is trying to sign in. It is raised
+ *   **only where an account would be created** — an identity that already has
+ *   one signs in at the quota exactly as it does under it, because refusing a
+ *   sign-in would turn a protection limit into an outage.
+ */
+declare const clientOidcErrorCode: z.ZodEnum<{
+    no_access: "no_access";
+    email_taken: "email_taken";
+    email_unverified: "email_unverified";
+    domain_not_allowed: "domain_not_allowed";
+    registration_closed: "registration_closed";
+    idp_unavailable: "idp_unavailable";
+    exchange_failed: "exchange_failed";
+    claims_incomplete: "claims_incomplete";
+    provider_misconfigured: "provider_misconfigured";
+    provider_disabled: "provider_disabled";
+    invalid_request: "invalid_request";
+    quota_exceeded: "quota_exceeded";
+}>;
+type ClientOidcErrorCode = z.infer<typeof clientOidcErrorCode>;
+/**
+ * **A pending MCP authorization, as the app's own consent screen reads it**
+ * (D7). Fleetless renders no page here either: `authorize` redirects to the
+ * app's `mcp_login_url` with an interaction id, the app authenticates the user
+ * with its normal UI, shows this, and approves or denies through the API.
  *
- * **The Fleetless session is ended before this is computed, unconditionally.**
- * Nothing below can fail in a way that leaves the caller logged in here — a
- * logout that depends on reaching a third party is not a logout.
+ * `client_name_verified` is `z.literal(false)`, and that is the whole point of
+ * the field. The name comes from an **unauthenticated** dynamic registration —
+ * the client typed it about itself, nobody checked it — so a consent screen
+ * that rendered it as though it were an identity would be teaching people to
+ * trust a string an attacker chooses. A literal rather than a boolean because
+ * there is no verified case to distinguish: an app that reads this field at all
+ * has to handle the untrusted one, and a `true` branch would be dead code
+ * pretending to be a safeguard.
+ */
+declare const clientMcpInteraction: z.ZodObject<{
+    id: z.ZodString;
+    app_id: z.ZodUUID;
+    client_name: z.ZodNullable<z.ZodString>;
+    client_name_verified: z.ZodLiteral<false>;
+    scopes: z.ZodArray<z.ZodString>;
+    already_granted: z.ZodBoolean;
+    expires_at: z.ZodISODateTime;
+}, z.core.$strip>;
+type ClientMcpInteraction = z.infer<typeof clientMcpInteraction>;
+/**
+ * **One standing MCP consent, as both withdrawal doors list it.**
  *
- * **Four outcomes**, and they are deliberately not collapsed into a nullable
- * URL. *No IdP was involved* and *an IdP was involved and publishes no
- * `end_session_endpoint`* are different things: the first needs no action and
- * the second means a session survives that this platform cannot end. A caller
- * that renders them identically is choosing to; a contract that cannot tell
- * them apart makes the choice for everyone.
+ * A grant is what lets a later authorization skip the app's consent screen:
+ * `clientMcpInteraction.already_granted` is a read of exactly this row. It is
+ * written when a person approves and it is removed by neither the client's
+ * registration lapsing nor its access token expiring — so without a door it
+ * was a decision a person could make once and never unmake.
  *
- * **This sentence said "three" for a whole wave, directly above a four-branch
- * union in this same file** — found by Momus-W9, along with the same number in
- * `sdk/src/auth.ts` and `sdk/README.md`. The type is derived
- * (`ClientLogoutResponse['idp_logout']`), so `tsc` had nothing to say, and the
- * sweep shows the mechanism plainly: `sdk d065447` is literally titled *"logout
- * says three separable things"* — correct when written, never carried forward
- * when `hint_unavailable` arrived in `b417d2a`.
+ * **Standing only.** A withdrawn grant is stamped rather than deleted, so the
+ * store still holds it; neither listing returns one. The question both doors
+ * ask is *what is connected right now*, and a row that answered "connected,
+ * but no" would be a state every caller has to filter for itself.
  *
- * The count is not the point. **`hint_unavailable` is precisely the case this
- * comment warns about** — the IdP session survives — so a caller who handles
- * the three documented branches drops it into an `else` they believe means
- * *nothing to do*.
+ * `client_name_verified` is `z.literal(false)` for the reason
+ * `clientMcpInteraction` gives at length: the name comes from an
+ * unauthenticated dynamic registration, the client chose it about itself, and
+ * a list that rendered it as an identity would be teaching people to trust a
+ * string an attacker picked. Here it matters more than on the consent screen,
+ * not less — a "connected apps" list is read long after the moment of
+ * approval, when nobody remembers what they clicked.
  */
-declare const clientLogoutResponse: z.ZodObject<{
-    idp_logout: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        status: z.ZodLiteral<"redirect">;
-        url: z.ZodURL;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"not_federated">;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"unsupported_by_idp">;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"hint_unavailable">;
-    }, z.core.$strip>, z.ZodObject<{
-        status: z.ZodLiteral<"session_unknown">;
-    }, z.core.$strip>], "status">;
+declare const mcpConsentGrant: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodNullable<z.ZodString>;
+    client_name_verified: z.ZodLiteral<false>;
+    granted_at: z.ZodISODateTime;
 }, z.core.$strip>;
-type ClientLogoutResponse = z.infer<typeof clientLogoutResponse>;
+type McpConsentGrant = z.infer<typeof mcpConsentGrant>;
 /**
  * Who the caller turned out to be. Returned by the "who am I" endpoint and by
  * the realtime `auth_ok` frame, so a client can render a session without
  * decoding a token itself — decoding a JWT in the client is how apps end up
  * trusting claims nobody verified.
  *
- * **Three kinds of caller reach the client API, not two.** Besides end users
- * and server keys, a **developer** does: spec §15.2 says the console's
- * playground runs over the real client API and appears in the audit as the
- * developer, and the console's own live views (robot list badges, the Live
- * tab) subscribe on `/realtime` as one. A developer is **org-scoped, not
+ * **Three kinds of caller reach the client API.** Besides app users and server
+ * keys, a **developer** does: the console's playground runs over the real
+ * client API and appears in the audit as the developer, and the console's own
+ * live views subscribe on `/realtime` as one. A developer is **org-scoped, not
  * app-scoped** — they own the configuration of every robot in their org — so
  * `app_id` and `role_id` are null for them, and roles do not filter what they
- * see. `kind` states this explicitly rather than leaving it to be inferred
- * from which id happens to be set.
+ * see. `kind` states this explicitly rather than leaving it to be inferred from
+ * which id happens to be set.
  *
- * **`act` is the real admin behind an impersonation** (spec
- * `2026-08-29-org-identity-redesign`, D4, the `act`-claim pattern of RFC
- * 8693). An Org Admins member entering an app through the interstitial
- * (`impersonationChoice`) gets a token whose *effective* identity is the role
- * or user they chose — that is what the rest of this shape describes — while
- * `act` names **the admin who is actually driving**. So every action can
- * audit as "Admin A as User B / as role X", and a client can render the "you
- * are acting as …" banner without decoding the token.
+ * **`end_user_id` became `app_user_id`, and that is a rename with a meaning.**
+ * The old subject was a member of the org's one pool, reachable through an
+ * assignment; the new one is a row that belongs to exactly one app. Renaming
+ * rather than keeping the key is deliberate: a consumer reading `.end_user_id`
+ * would have typechecked and meant something subtly different, which is the
+ * quietest way for a cut like this to go wrong.
  *
- * **Optional, not a nullable actor, for `orgUser.tier`'s reason:** absence
- * means *this is an ordinary session, nobody is delegating*, which is not the
- * same fact as *the actor is unknown*. The overwhelming majority of sessions
- * are ordinary and carry no `act` at all; a session that has one is a
- * delegation and says who by. The schema cannot check that `act` is present
- * exactly when the effective identity was impersonated — that pairing is the
- * cloud's, minted at the authorize step. Only the admin's **id** rides here:
- * the label is resolved by whoever renders it, not carried as a second
- * unverified name on the wire.
+ * **`act` is gone.** It named the org admin behind an impersonation (the RFC
+ * 8693 pattern). Impersonation is deleted with no successor (D1), so a field
+ * that could still arrive would describe a delegation nothing can mint — and a
+ * client rendering "you are acting as …" from it would be showing a state the
+ * platform cannot enter.
  */
 declare const clientIdentity: z.ZodObject<{
     kind: z.ZodEnum<{
-        server_key: "server_key";
         developer: "developer";
-        end_user: "end_user";
+        server_key: "server_key";
+        app_user: "app_user";
     }>;
     developer_id: z.ZodNullable<z.ZodUUID>;
-    end_user_id: z.ZodNullable<z.ZodUUID>;
+    app_user_id: z.ZodNullable<z.ZodUUID>;
     server_key_id: z.ZodNullable<z.ZodUUID>;
     app_id: z.ZodNullable<z.ZodUUID>;
     role_id: z.ZodNullable<z.ZodUUID>;
     email: z.ZodNullable<z.ZodEmail>;
-    act: z.ZodOptional<z.ZodObject<{
-        admin_user_id: z.ZodUUID;
-    }, z.core.$strict>>;
 }, z.core.$strip>;
 type ClientIdentity = z.infer<typeof clientIdentity>;
 
@@ -423,9 +470,9 @@ declare const assetSyncStatus: z.ZodObject<{
     sync_id: z.ZodUUID;
     robot_id: z.ZodUUID;
     state: z.ZodEnum<{
+        failed: "failed";
         running: "running";
         succeeded: "succeeded";
-        failed: "failed";
     }>;
     done: z.ZodNumber;
     total: z.ZodNumber;
@@ -467,9 +514,9 @@ declare const assetListResponse: z.ZodObject<{
         sync_id: z.ZodUUID;
         robot_id: z.ZodUUID;
         state: z.ZodEnum<{
+            failed: "failed";
             running: "running";
             succeeded: "succeeded";
-            failed: "failed";
         }>;
         done: z.ZodNumber;
         total: z.ZodNumber;
@@ -543,79 +590,9 @@ type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
  * list is the shared vocabulary, not a closed set, so a new refusal never
  * needs a contracts release before it can be reported honestly.
  */
-declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "invite_expired", "invite_used", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "asset_too_large", "dynamic_registration_disabled", "client_limit_reached", "identity_conflict", "identity_not_provisioned", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "group_not_deletable", "group_in_use", "target_state_conflict", "mcp_access_denied", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml"];
+declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "asset_too_large", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
 type ErrorCode = (typeof ERROR_CODES)[number];
 
-/**
- * **What an end user sees about their own consents, and why it is not
- * `consentGrant` (W9c, DEF-099).**
- *
- * `consentGrant` is the *record* — four ids and a scope string. A person
- * deciding whether to revoke something needs to recognise it, and an id is
- * not recognisable. So this carries the names that were on the screen when
- * they consented: the client's, the app's, and the role's.
- *
- * `client_id` stays, because it is what a revocation addresses — the names
- * are for reading, the id is for acting.
- */
-declare const consentGrantSummary: z.ZodObject<{
-    client_id: z.ZodString;
-    client_name: z.ZodString;
-    app_id: z.ZodUUID;
-    app_name: z.ZodString;
-    role_id: z.ZodUUID;
-    role_name: z.ZodString;
-    scope: z.ZodString;
-    granted_at: z.ZodISODateTime;
-}, z.core.$strip>;
-type ConsentGrantSummary = z.infer<typeof consentGrantSummary>;
-/**
- * **Revoking one grant must end the access it authorised, not merely forget
- * that it happened (W9c, DEF-099).**
- *
- * The register row is about a user who wants a specific client to stop, and
- * the failure mode to avoid is a revocation that deletes the consent row
- * while every already-issued token keeps working until it expires. So the
- * response says what was actually ended, and a caller can tell *nothing
- * matched* from *matched and ended*.
- *
- * `tokens_revoked` is the count of refresh **families** ended. It is not a
- * count of access tokens, and deliberately so: an access token is stateless
- * and short-lived, and a number that claimed to have revoked one would be the
- * kind of sentence this project keeps having to take back.
- *
- * **What actually happens to the access token is stronger than this comment
- * first claimed, and narrower than its correction (W9c, 2026-08-19).** The
- * first version said *"let the access token expire"*. It does not. The
- * correction then said *"the same access token dies"*, which is true and
- * under-specified — Data-W9c read `resolveAnyToken` instead of copying the
- * sentence and found what the check is actually bound to:
- *
- *   `if (claims.client_id) { ...consent-grant lookup... }`
- *
- * So the immediate death is scoped to **`client_id`, not to a session and not
- * to the end user.** Every currently-valid token issued through *this
- * client's* OAuth flow for this end user dies at once — including a second
- * tab holding a different token from the same client. A plain `auth.login()`
- * session is untouched, because it carries no `client_id` for the check to
- * read, and a token bound to a *different* client is untouched too.
- *
- * That distinction is the whole point of revoking one grant rather than
- * logging somebody out: *"without touching any other client's access"* is
- * what this route promises, and the check is what makes it true.
- *
- * That is a better outcome than the contract promised, and it is written down
- * here for one reason: **a caller must not build on the weaker sentence.** If
- * this platform ever moves to stateless verification without the revocation
- * re-check, the access token would start living out its TTL again, and
- * anything that quietly relied on immediate death would break silently.
- */
-declare const consentRevokeResponse: z.ZodObject<{
-    revoked: z.ZodBoolean;
-    tokens_revoked: z.ZodNumber;
-}, z.core.$strip>;
-type ConsentRevokeResponse = z.infer<typeof consentRevokeResponse>;
-
 /**
  * Codes the SDK produces itself rather than relaying from the server. Kept
  * out of `@fleetless/contracts`' `ERROR_CODES` deliberately — that list is
@@ -656,7 +633,12 @@ type ConsentRevokeResponse = z.infer<typeof consentRevokeResponse>;
  *   signature and is still passing an options object third; and a
  *   `concurrency` on `assets.prepareUrdfScene` that is not a positive
  *   integer, which would otherwise fetch nothing and return a scene that
- *   renders blank with no error to explain why. All three are refused
+ *   renders blank with no error to explain why. **A fourth since 3.0.0:**
+ *   every `auth` method needing an app user's own session, called on a client
+ *   built with a `serverKey` — `register`, `login`, `logout`, the password
+ *   and invitation calls, both OIDC calls, the two MCP decisions and the two
+ *   grant calls. Those threw a bare `Error` before, which a caller could only
+ *   catch by message. All of them are refused
  *   before any request is sent — as a rejection, since every one of those
  *   methods is `async`. A client-side mistake to fix, not something a
  *   server response could ever produce, which is why this code belongs here
@@ -675,17 +657,6 @@ type ConsentRevokeResponse = z.infer<typeof consentRevokeResponse>;
  *   rather than left to surface as a confusing downstream failure from
  *   `URDFLoader.parse(undefined)` or similar — the caller's fix is "sync a
  *   URDF first", which this error can say directly.
- * - `no_hosted_login_attempt`: `auth.completeHostedLogin()` was called with
- *   an empty `expectedState` — nothing was persisted for this attempt. A
- *   callback landing in a different tab or window than the one that called
- *   `beginHostedLogin`, a restored session, or storage cleared in between
- *   all produce exactly this, and none of them is an attack. Told apart
- *   from `state_mismatch` on purpose: the two diagnoses have different
- *   remedies ("check how you persisted the value" versus "this response
- *   belongs to a login you did not start"). It also closes a real gap —
- *   comparing two *empty* strings with `!==` is `false`, so without this
- *   check first, a caller with nothing persisted at all could reach
- *   `state_mismatch`'s comparison having contributed no defence whatsoever.
  * - `aborted`: `assets.prepareUrdfScene()` was given an `AbortSignal` and it
  *   fired — either already-aborted before the call started, or mid-flight
  *   while a fetch was in progress. Normalized to this one code regardless of
@@ -698,18 +669,27 @@ type ConsentRevokeResponse = z.infer<typeof consentRevokeResponse>;
  *   created (`blob:` URLs) is revoked before this throws — an aborted load
  *   must not leak what it fetched before the signal fired, the same
  *   guarantee a failed load already had.
- * - `state_mismatch`: `auth.completeHostedLogin()` was called with a `state`
- *   that does not match the `expectedState` its own `beginHostedLogin()`
- *   returned for this attempt (or with no `state` at all — `beginHostedLogin`
+ * - `state_mismatch`: `auth.completeOidcLogin()` was called with a `state`
+ *   that does not match the `expectedState` its own `beginOidcLogin()`
+ *   returned for this attempt — or with no `state` at all (`beginOidcLogin`
  *   always sets one, so a callback carrying none does not look like a reply
- *   to a flow this client started). Thrown before `/oauth/token` is ever
- *   called: RFC 6749 section 10.12's whole point is that a caller must not
- *   complete an authorization response it did not itself request, so this
- *   check happens client-side, first, rather than being left to the server
- *   to catch — by which point a code exchange would already have been
- *   attempted for a flow this client never started.
+ *   to a flow this client started), or with an **empty `expectedState`**,
+ *   meaning nothing was persisted for this attempt at all. That last case is
+ *   folded in rather than given its own code: two empty strings compare
+ *   equal, so it has to be checked explicitly or the comparison defends
+ *   nothing for exactly the callers most likely to hit it — but a caller
+ *   branching on the code has the same next step either way, which is to
+ *   start the sign-in again. Which of the two happened is in the message,
+ *   because the *developer's* remedies do differ ("check how your app
+ *   persisted the value" versus "this response belongs to a sign-in you did
+ *   not start"). Thrown before `/api/client/oidc/exchange` is ever called:
+ *   RFC 6749 section 10.12's whole point is that a caller must not complete
+ *   an authorization response it did not itself request, so this check
+ *   happens client-side, first, rather than being left to the server to
+ *   catch — by which point a one-time code would already have been spent for
+ *   a flow this client never started.
  */
-declare const SDK_ERROR_CODES: readonly ["no_session", "no_websocket", "unparseable_error", "command_timeout", "command_outcome_unknown", "unexpected_response", "invalid_option", "untrusted_absolute_url", "state_mismatch", "no_hosted_login_attempt", "no_urdf_synced", "aborted"];
+declare const SDK_ERROR_CODES: readonly ["no_session", "no_websocket", "unparseable_error", "command_timeout", "command_outcome_unknown", "unexpected_response", "invalid_option", "untrusted_absolute_url", "state_mismatch", "no_urdf_synced", "aborted"];
 /**
  * The union of `SDK_ERROR_CODES` — the SDK's own client-side error
  * vocabulary. A `FleetlessError` whose `code` is one of these was raised by
@@ -1270,389 +1250,351 @@ declare class InMemoryTokenStore implements TokenStore {
 }
 
 /**
- * `beginHostedLogin()`'s input: the OAuth client the developer registered
- * for this app, where the browser should come back to, and optionally what
- * the resulting token should be usable against.
+ * `register()`'s input. The app identifier is **not** here: the client already
+ * holds one (`createClient({ appIdentifier })`) and sends it itself, so there
+ * is no way for a caller to register somebody into a different app than the
+ * one this client speaks for.
  */
-interface BeginHostedLoginOptions {
+interface RegisterOptions {
+    /** The address the verification mail goes to. Nothing works until that link is spent. */
+    email: string;
+    /** At least 12 characters — `clientRegisterRequest` refuses less with a `validation_error`. */
+    password: string;
     /**
-     * The opaque `client_id` issued when the developer registered this app's
-     * OAuth client (console, App Settings). **Never `appIdentifier`** — they
-     * are deliberately different identifiers — the contracts call this "the
-     * `client_id` on the wire: opaque, and not the app identifier".
+     * What the app should call this person. Optional, and **omitted from the
+     * request entirely** when you do not pass it — `clientRegisterRequest` is a
+     * strict schema, so a key carrying `undefined` would be a `422` rather than a
+     * default.
      */
-    clientId: string;
+    displayName?: string;
+}
+/** `acceptInvitation()`'s input — the token out of the mailed link, plus the password the account gets. */
+interface AcceptInvitationOptions {
+    /** The `token` from the invitation link the developer's app was linked to. */
+    token: string;
+    /** At least 12 characters. The invitation fixes the role; this call fixes the credential. */
+    password: string;
+    /** Optional, and omitted from the request entirely when absent — same strict-schema reason as `RegisterOptions.displayName`. */
+    displayName?: string;
+}
+/** One sign-in button on the app's own login screen, as `listProviders()` lists it. */
+interface ProviderButton {
+    /** What `beginOidcLogin` addresses this provider by. */
+    slug: string;
+    /** The label the developer configured, to be rendered on the button. */
+    name: string;
+}
+/** `beginOidcLogin()`'s input: which provider, and where Fleetless should send the browser back to. */
+interface BeginOidcLoginOptions {
+    /** A `slug` from `listProviders()`. An unknown one is a `404` when the browser reaches the start route, not here. */
+    slug: string;
     /**
-     * Must be registered, byte-for-byte, as one of that client's
-     * `redirect_uris` — matching at the server is exact-string, never a
-     * prefix (the contracts' `redirectUri` doc comment says why).
+     * Where the browser comes back to with `?code=…&state=…` (or `?error=…`).
+     * Checked against the app's **allowed origins** server-side, by origin — so
+     * the path is yours to choose and the origin is not.
+     *
+     * **Two shapes are refused outright, before the origin is compared**, and
+     * neither refusal mentions them: a URL carrying a **fragment**
+     * (`https://app.example.com/#/auth/callback`) and one carrying **userinfo**
+     * (`https://someone@app.example.com/cb`). Both come back as a flat
+     * `400 invalid_redirect_uri` reading "The redirect_uri is not an origin this
+     * app answers for", which sends people to re-check an allow-list that was
+     * never the problem.
+     *
+     * The fragment case is the one that costs time, because hash routing is the
+     * default for a static-hosted SPA with no server rewrite. Give the callback
+     * a real path (`/auth/callback`) and let your router pick the hash route up
+     * from there; a fragment is a browser-side construct the redirect could not
+     * carry a code in anyway.
      */
     redirectUri: string;
+}
+/** What `beginOidcLogin()` returns. Nothing here has touched the network. */
+interface OidcLoginRequest {
     /**
-     * The OAuth scopes to request, space-separated. Omit it to get the
-     * client's registered default, which is what an ordinary app login wants.
-     */
-    scope?: string;
-    /**
-     * RFC 8707 audience binding: the resource this
-     * session's token should be usable against. **Omit it for an ordinary app
-     * login.** A token with no `resource` carries no `aud` and works
-     * unrestricted against this app's own REST surface exactly as it always
-     * has; that path is unaffected by this field's existence. Only a caller
-     * that is itself going to present the token to an audience-checking
-     * resource needs to ask for one.
-     *
-     * **`/oauth/authorize` accepts exactly two shapes** — anything else is
-     * refused with `invalid_target` on the redirect back, before a code is
-     * ever issued (the cloud's own known-resource check):
-     *
-     * - `<base>/mcp-stub/resource` — the global OAuth resource stub, matched
-     *   byte-for-byte.
-     * - `<base>/mcp-stub/resource/<app_identifier>` — the per-app stub, and
-     *   only for **the calling client's own app**. This is an existence check
-     *   plus an ownership check, not a shape check: the app must exist *and*
-     *   be the one this `clientId` is registered to, so a client on app A can
-     *   never be minted a token whose `aud` names app B.
-     *
-     * Both are served and validated by the platform's resource stub, whose
-     * validator refuses a token with **no** `aud` exactly as hard as one with
-     * the wrong `aud` —
-     * "unscoped" must never read as "for me" — comparing by equality, never
-     * by prefix.
-     *
-     * **`<base>/mcp/<app_identifier>` is not a resource any more.** There is
-     * no per-app MCP endpoint: the cloud registers one central, non-parametric
-     * `POST /mcp` (the contracts' `MCP_ENDPOINT_PATH`), and the
-     * `/oauth/authorize` branch that used to
-     * accept a `/mcp/<app>` resource was deleted along with the app-level
-     * `mcp_enabled` flag. Asking for one now yields `invalid_target` for
-     * every app, **including your own**. The central MCP endpoint has its own
-     * OAuth flow, which this SDK's hosted login does not drive —
-     * `beginHostedLogin` always targets
-     * `OAUTH_PATHS.authorize`.
-     *
-     * Whatever you name here is re-checked at the token exchange: it must
-     * match what the code was authorized for, and it must still name a
-     * resource this client may be issued a token for.
+     * Send the end user's browser here. **This SDK does not navigate** — it has
+     * no opinion about whether that is a full page load, a popup or a native web
+     * view, the same boundary `cameras.live` draws by handing back a URL and a
+     * token and stopping there.
      */
-    resource?: string;
-}
-/** What `beginHostedLogin()` returns — nothing here has touched the network yet. */
-interface HostedLoginRequest {
-    /** Send the end user's browser here to start the hosted login page. */
     url: string;
     /**
-     * Persist this alongside `codeVerifier` before navigating away, and pass
-     * both back into `completeHostedLogin`. **This SDK does not persist them
-     * for you.** The redirect back to `redirectUri` is a fresh page load for a
-     * browser app — nothing kept in this SDK's own memory survives it (the
-     * same reasoning `TokenStore` states: the SDK itself never assumes a
-     * browser, or any storage, exists). An in-memory default
-     * here would not be merely suboptimal, it would be broken for the primary
-     * use case while looking like it worked for anything that never actually
-     * navigates away. `sessionStorage`, a signed cookie, or a plain variable
-     * (a popup flow that never truly navigates) are all valid — that choice is
-     * the caller's.
+     * Persist this next to `codeVerifier` **before navigating away**, and pass
+     * both back into `completeOidcLogin`. The SDK does not persist them for you:
+     * the redirect back is a fresh page load for a browser app, and nothing kept
+     * in this SDK's memory survives it. `sessionStorage`, a signed cookie or a
+     * plain variable (a popup flow that never truly navigates) are all valid —
+     * that choice is the caller's, and an in-memory default here would look like
+     * it worked right up until the first real redirect.
      */
     state: string;
     /**
-     * The PKCE code verifier for this attempt. Persist it exactly as
-     * `state` above and pass it back to `completeHostedLogin` — it is what
-     * proves the code exchange comes from the client that started the flow.
+     * The PKCE code verifier for this attempt — persist it exactly as `state`.
+     * **The app runs its own PKCE against Fleetless**, a second exchange
+     * independent of the one Fleetless runs against the identity provider, which
+     * is what makes the one-time code in the redirect worth nothing to whoever
+     * else reads that URL.
      */
     codeVerifier: string;
 }
-/** `completeHostedLogin()`'s input — the redirect back, plus what `beginHostedLogin` returned for this same attempt. */
-interface CompleteHostedLoginOptions {
-    /** The `code` query parameter from the redirect back to `redirectUri`. */
+/** `completeOidcLogin()`'s input — the redirect back, plus what `beginOidcLogin` returned for this same attempt. */
+interface CompleteOidcLoginOptions {
+    /** The `code` query parameter from the redirect back to `redirectUri`. It lives 60 seconds. */
     code: string;
     /** The `state` query parameter from that same redirect. */
     state: string;
-    /**
-     * The `state` this attempt's `beginHostedLogin` returned. Checked against
-     * `state` above **before any network call** — the whole point of RFC
-     * 6749 section 10.12 is that a caller must not complete an authorization
-     * response it did not itself request.
-     */
+    /** The `state` this attempt's `beginOidcLogin` returned. Compared **before any network call**. */
     expectedState: string;
-    /** The `codeVerifier` this attempt's `beginHostedLogin` returned. */
+    /** The `codeVerifier` this attempt's `beginOidcLogin` returned. */
     codeVerifier: string;
-    /** Must be the exact same `client_id` passed to `beginHostedLogin`. */
-    clientId: string;
-    /** Must be the exact same string passed to `beginHostedLogin`. */
-    redirectUri: string;
-    /**
-     * Must be the exact same string passed to `beginHostedLogin`, if any.
-     * Resending it here is not what binds the audience — the server already
-     * bound `resource` to the authorization code at `/oauth/authorize` and
-     * mints `aud` from that stored value regardless of what this call sends —
-     * but RFC 8707 section 2 expects a client to name the resource at both steps,
-     * and the cloud rejects a *mismatched* resend outright (`invalid_target`).
-     * Omit it here exactly when it was omitted at `beginHostedLogin`.
-     */
-    resource?: string;
 }
 /**
- * What `logout()` resolves with — five separable facts, not one nullable
- * URL, mirroring the wire's `clientLogoutResponse`.
- *
- * **`idp_logout` is `null` whenever the server never answered**, which
- * happens for two different reasons: there was no local session to ask
- * about, or the request itself failed. Either way there is nothing to
- * report — not even "not federated", because this client never learned that
- * either.
- *
- * `revoked` does not identify which of the two you got. It is `false` only
- * for the failed request; **a logout with no local session at all resolves
- * `{ revoked: true, idp_logout: null }`**, since nothing lingers
- * server-side and that counts as revoked. So `revoked: false` does imply
- * `idp_logout: null`, and the converse does not hold. Do not read the two
- * fields as one bit.
+ * What `approveMcpInteraction`/`denyMcpInteraction` resolve with: **where to
+ * send the browser**, and nothing else.
  *
- * When a real response did come back, `revoked` is `true` and `idp_logout`
- * is one of:
- *
- * - `{ status: 'redirect', url }` — send the browser here to end the
- *   session at the IdP too. Nothing else in this SDK does that navigation
- *   for you (same "this SDK is thin" reasoning as `cameras.live`).
- * - `{ status: 'not_federated' }` — this session never came from an IdP;
- *   there is nothing else to end.
- * - `{ status: 'unsupported_by_idp' }` — it did, and the IdP publishes no
- *   `end_session_endpoint` (RP-initiated logout is optional in OIDC).
- * - `{ status: 'hint_unavailable' }` — it did, the IdP *can* end the
- *   session, and Fleetless has nothing to ask it with: the stored
- *   `id_token_hint` could not be decrypted, or the session predates the fix
- *   that started keeping one.
- * - `{ status: 'session_unknown' }` — the server did not find this session at
- *   all (the token was unknown, already superseded, revoked, or expired), so
- *   it can say **nothing** about an IdP.
+ * A denial carries a redirect too, with `error=access_denied` on it — a client
+ * that is refused has to learn so from its own callback rather than from a page
+ * nobody sent it, so both outcomes end the same way for the app: navigate here.
+ */
+interface McpInteractionDecision {
+    /** The absolute URL to navigate to. Wire field `redirect_to`. */
+    redirectTo: string;
+}
+/**
+ * Who the caller is, reachable as `client.auth` — the whole client auth API of
+ * spec §4, as JSON.
  *
- * **`unsupported_by_idp` and `hint_unavailable` both mean the IdP session
- * survives and this platform cannot end it** — do not render either one the
- * same as `not_federated`; that reports a session as fully ended when it
- * isn't.
+ * **Fleetless serves an app user no page.** The developer's own UI owns every
+ * screen: login, registration, verification, invitation acceptance, password
+ * reset, the provider buttons and the MCP consent. These methods are what those
+ * screens call. The hosted, app-branded login and consent pages this SDK used
+ * to drive are gone, along with `beginHostedLogin`/`completeHostedLogin`.
  *
- * **`session_unknown` is a different kind of nothing, and the reason it
- * exists is a second logout.** A double click, a repeated POST, an
- * app that logs out on unmount *and* on a route change: the last call wins,
- * and before this outcome existed it answered `not_federated` — a positive
- * claim about an IdP the server had never looked up. An app that treats it as
- * *"fully logged out"* skips a redirect the **first** call may well have
- * returned, and the user stays signed in at the IdP after clicking log out.
+ * **The enumeration discipline is the design's, and it shapes this surface.**
+ * `register`, `resendVerification` and `requestPasswordReset` resolve for every
+ * policy-allowed request whether or not the address exists, and `login` answers
+ * the identical `invalid_credentials` for a wrong password, a blocked account
+ * and an unverified one. So: *resolving does not mean an account exists*, and
+ * the only honest refusals are the ones about policy rather than about a
+ * person — `registration_closed`, `domain_not_allowed`, `quota_exceeded`.
  *
- * Note that `revoked` cannot help you here either: it reports whether the
- * HTTP call succeeded, not whether a session was found — so this case
- * arrives as `{ revoked: true, idp_logout: { status: 'session_unknown' } }`,
- * never as `null`.
+ * **A client built with a `serverKey` refuses everything that needs an app
+ * user's own session** with `invalid_option`, before any request. `me()`,
+ * `listProviders()`, `mcpInteraction()` and `oidcErrorFromCallback()` still
+ * work on one: the first is what a server key is *for*, the next two are public
+ * reads the cloud answers without any credential at all, and the last touches
+ * no network.
  */
-interface LogoutResult {
-    /**
-     * Whether the server-side revoke actually happened. It reports the fate
-     * of the HTTP call, not whether a session was found — `false` means the
-     * refresh family may still be alive even though this client has
-     * forgotten it.
-     */
-    revoked: boolean;
+interface AuthApi {
     /**
-     * What the server could say about the identity provider behind this
-     * session, or `null` when there was no answer to report at all — either
-     * because there was no local session to ask about, or because the request
-     * failed. `null` is **not** the same as `not_federated`, which is a real
-     * finding about a real session.
-     *
-     * When it is not `null` it is one of five statuses: `redirect` (with a
-     * `url` to send the browser to, to end the session at the identity
-     * provider too), `not_federated` (this session never came from one),
-     * `unsupported_by_idp` (it did, and the provider offers no
-     * RP-initiated logout), `hint_unavailable` (it did, the provider can end
-     * the session, and Fleetless has nothing to ask it with), or
-     * `session_unknown` (the server did not find this session, so it can say
-     * nothing about a provider).
-     *
-     * **`unsupported_by_idp` and `hint_unavailable` both mean the identity
-     * provider's session survives and this platform cannot end it.** Render
-     * either one like `not_federated` and you report a session as fully ended
-     * when it is not.
+     * Self-registration. Writes the account as `pending_verification` and mails
+     * the app's verification link; **the account cannot log in until that link is
+     * spent** (`verifyEmail`).
+     *
+     * Resolves on the route's `202` — which the cloud answers for every
+     * policy-allowed request, whether the address was new or already known. It is
+     * not a claim that an account was created, and an app that renders it as one
+     * ("welcome, Ada!") is showing a stranger the enumeration oracle this whole
+     * family is built to avoid. Render "check your mail" instead.
+     *
+     * Throws a `FleetlessError` carrying the cloud's own code for a refusal, and
+     * that is the distinction this method exists to preserve: `registration_closed`
+     * (the app has self-registration off), `domain_not_allowed` (the address is
+     * outside the app's allowed domains), `quota_exceeded` (the org has as many
+     * app users as its quota allows) and `not_found` (no app carries this
+     * client's `appIdentifier`) are all things the app can say out loud, because
+     * none of them is about whether a person exists.
      */
-    idp_logout: ClientLogoutResponse['idp_logout'] | null;
-}
-/**
- * Who the caller is, reachable as `client.auth`. A client built with a
- * `tokenStore` uses the full surface. One built with a `serverKey` already
- * has an identity and no user session, so **`me()` is the only method it
- * can call** — `login`, `beginHostedLogin`, `completeHostedLogin`,
- * `logout`, `changePassword` and `passwordResetUrl` all throw on one.
- */
-interface AuthApi {
-    /** Exchanges email + password, and the client's configured app identifier, for a session. */
-    login(email: string, password: string): Promise<void>;
+    register(input: RegisterOptions): Promise<void>;
     /**
-     * Starts the hosted login flow: a Fleetless-served
-     * login page an app's end user is redirected to, with optional
-     * per-app IdP federation. Builds the `/oauth/authorize` URL (Authorization
-     * Code + PKCE, S256 only — OAuth 2.1 removes `plain`) and generates the
-     * `state`/`codeVerifier` PKCE and CSRF protection need. **Makes no network
-     * call** — everything here is local, so nothing about the app, the
-     * client, or the redirect URI is validated until the browser actually
-     * reaches `/oauth/authorize`.
-     *
-     * Async only because computing the S256 `code_challenge` needs
-     * `crypto.subtle.digest`, which the Web Crypto API only ever offers as a
-     * promise — there is no synchronous digest to call instead.
+     * Spends a verification token and **stores the session it answers with**, so
+     * the person is not asked to log in immediately after proving they can read
+     * the mail.
+     *
+     * `token_spent` covers unknown, expired and already-used alike — one code,
+     * because the remedy is one thing: ask for a fresh link with
+     * `resendVerification`. An app rendering this refusal should offer that.
      */
-    beginHostedLogin(options: BeginHostedLoginOptions): Promise<HostedLoginRequest>;
+    verifyEmail(token: string): Promise<void>;
+    /** Asks for the verification mail again. Resolves on `202` for every policy-allowed request, existing address or not — same reason as `register`. */
+    resendVerification(email: string): Promise<void>;
     /**
-     * Completes the hosted login flow: checks `state` against `expectedState`
-     * (before any network call — see `CompleteHostedLoginOptions.expectedState`),
-     * exchanges `code` for tokens at `/oauth/token`, and stores them via the
-     * same `tokenStore` `login()` uses.
-     *
-     * **Two distinct refusals before that check, not one.** An empty
-     * `expectedState` throws `no_hosted_login_attempt` — nothing was
-     * persisted for this attempt (a different tab, a restored session,
-     * cleared storage), not necessarily an attack. Only once `expectedState`
-     * is actually present does a mismatch (or a missing `state` on the
-     * callback itself) throw `state_mismatch`. The two are told apart on
-     * purpose: they call for different remedies, and collapsing them would
-     * tell a developer debugging an ordinary storage gap that their app is
-     * under attack.
-     *
-     * Once past that check and the exchange completes, `me()`, `logout()`,
-     * `changePassword()` and silent refresh all behave identically afterwards,
-     * regardless of which flow the session started from. Both routes into a
-     * session end at the same Fleetless token: not merely that the bytes
-     * match, but that every existing code path treats the result the same
-     * way.
-     *
-     * The wire response is the envelope of RFC 6749 section 5.1 (`token_type`, optional
-     * `scope`), not `sessionTokens` — this method normalizes one into the
-     * other before storing. **Refresh needs no separate handling**: the cloud
-     * mints these tokens through the same session mechanism `/api/client/login`
-     * uses (same `refresh_tokens` row, same rotation), so the existing silent
-     * refresh (`/api/client/refresh`) already works for a hosted-login
-     * session — nothing about the origin of a session is tracked or needs to
-     * be.
-     *
-     * Throws with the OAuth error code as `.code` (e.g. `invalid_grant` for an
-     * expired or already-used `code`) if the exchange itself fails — a
-     * different vocabulary from every other method on this interface, because
-     * `/oauth/token` answers in the shape of RFC 6749 section 5.2, not `apiError`.
-     *
-     * **Makes exactly one request to `/oauth/token` — never retried, no
-     * timeout-and-resend, no internal concurrency of its own.** Stated
-     * because the constraint that matters here is not this method's, it is
-     * the caller's: **never call this a second time for the same `code`
-     * while a first call is still in flight** (a plain "the first attempt
-     * looked like it timed out, so retry" is exactly the shape this warns
-     * against — it is not a defect in this method, since this method itself
-     * has nothing that could ever cause that). The platform treats a second
-     * presentation of an authorization code as theft and revokes the whole
-     * token family it belongs to, deliberately, even though a plain
-     * double-submission looks identical on the wire —
-     * because the blast radius is bounded (only a caller already holding the
-     * correct `code_verifier` and `client_id` can trigger it, so a merely
-     * *sniffed* code cannot lock anyone out) and the alternative is a
-     * narrower defence against a real theft.
-     *
-     * **What actually happens if two requests race, measured:**
-     * one of the two receives `200` with a refresh token that the server has
-     * already revoked. The access token in that same response keeps working
-     * normally for the rest of its short TTL — nothing about the race is
-     * visible yet. The failure surfaces at this session's **first silent
-     * refresh**, as `token_revoked`, potentially many minutes after the race
-     * that actually caused it and with nothing in that later error pointing
-     * back to a retry that "worked". If your own framework, an HTTP client
-     * wrapper, or a user's impatient double-click can cause this method to
-     * be invoked twice concurrently for the same redirect, guard against
-     * that at the call site — a simple in-flight flag or disabling the
-     * triggering control is enough, since there is only ever one legitimate
-     * exchange per authorization code.
+     * Exchanges email + password, and the client's configured app identifier, for
+     * a session.
+     *
+     * `invalid_credentials` is answered identically for a wrong password, a
+     * blocked account and one still waiting to verify. Do not try to tell them
+     * apart — there is nothing in the answer that does, deliberately.
      */
-    completeHostedLogin(options: CompleteHostedLoginOptions): Promise<void>;
+    login(email: string, password: string): Promise<void>;
     /**
-     * Ends the session: revokes the whole refresh-token family server-side
-     * (a stolen refresh token stops working immediately) and closes this
-     * client's live realtime connection, if it has one. Then clears the
-     * local store. Never rejects and always clears the store, even if the
-     * server call fails: a user who presses "log out" must end up logged out
-     * locally regardless of the network. `revoked` reports whether the
-     * server-side revoke actually happened — `false` means the refresh
-     * family may still be alive server-side even though this client has
-     * forgotten it; an app that cares (a kiosk, a shared workstation) can
-     * warn the user or retry, one that doesn't can ignore it.
+     * Ends the session: revokes the whole refresh-token family server-side (a
+     * stolen refresh token stops working immediately), closes this client's live
+     * realtime connection if it has one, and clears the local store.
+     *
+     * **Never rejects, and always clears the store**, even if the server call
+     * fails: a user who presses "log out" must end up logged out locally
+     * regardless of the network.
      *
      * **What this does not do:** invalidate the access token already issued.
-     * Access-token checks are stateless (a signed JWT, verified without a
-     * server-side lookup) — logout has nothing to flip on that token, only
-     * on the refresh family behind it. A token stolen before logout keeps
-     * working on REST, and can still open a *new* realtime connection, until
-     * it expires on its own — at most 15 minutes. This is a deliberate
-     * boundary of the stateless-JWT design (the same one that lets a role
-     * change, a block, or a membership removal take effect on the very next
-     * request without a fresh token), not a bug — but a kiosk or shared
-     * workstation needs to know that number.
-     *
-     * **Nor does it end a federated session at the identity provider.**
-     * Ending the Fleetless session and ending the IdP session are
-     * two different things — see `LogoutResult.idp_logout`. This method does
-     * not act on that information itself (no redirect, no fetch to the IdP);
-     * it only reports what the server found, the same "this SDK stays thin"
-     * boundary as everywhere else (`cameras.live` hands back a URL and a
-     * token and stops there too).
-     *
-     * **`idp_logout` is `null` when there was no server answer to report** —
-     * and that is *not* the same as `revoked === false`.
-     *
-     * Calling `logout()` with **no local session** returns
-     * `{ revoked: true, idp_logout: null }`, so `null` is not the same as
-     * `revoked === false` and the two fields are not one bit. TypeScript
-     * catches a caller who forgets (the type is `| null`); a JavaScript caller
-     * does not.
-     *
-     * So: **`null` means this client had nothing to send or the request never
-     * answered.** It is not `not_federated`, which is a real finding about a
-     * real session — conflating the two is the ambiguity this shape exists to
-     * remove, and it is the reason to read both fields rather than one.
+     * Access-token checks are stateless (a signed JWT, verified without a lookup),
+     * so logout has nothing to flip on that token — only on the refresh family
+     * behind it. A token stolen before logout keeps working on REST, and can
+     * still open a *new* realtime connection, until it expires on its own, at
+     * most 15 minutes. That is a deliberate boundary of the stateless-JWT design,
+     * not a bug, but a kiosk or a shared workstation needs to know the number.
+     *
+     * **Nor does it end a session at the identity provider.** It used to report
+     * what was left of one; that apparatus belonged to the hosted login, where
+     * Fleetless owned the browser. The app owns it now, and an app that wants to
+     * end a provider session redirects there itself — knowing its own provider,
+     * which Fleetless never did better than it.
      */
-    logout(): Promise<LogoutResult>;
-    /** Who the caller turned out to be, without decoding a token client-side. */
+    logout(): Promise<void>;
+    /** Who the caller turned out to be, without decoding a token client-side — which is how apps end up trusting claims nobody verified. */
     me(): Promise<ClientIdentity>;
     /**
-     * Changes the current end user's password.
-     *
-     * `currentPassword` is required by the server even though the session
-     * already proves identity — it is what stops a stolen *session* from
-     * becoming a stolen *account* (see `passwordChangeRequest` in
-     * `@fleetless/contracts`).
-     *
-     * **Every other session of this identity is revoked on success, and this
-     * call's own session is re-issued, not left alone.** `passwordChangeRequest`
-     * carries nothing that identifies the caller's own refresh family, so the
-     * server cannot spare one token out of the family it just revoked — it
-     * revokes all of them and hands back a fresh pair, which this method
-     * stores exactly like `login` does. Skipping that store would leave the
-     * caller holding tokens the server has already revoked, working only
-     * until the access token expires and then silently logged out —
-     * indistinguishable from the change having failed, which is the one
-     * outcome this route exists to prevent. A user with other tabs or
-     * devices logged in will see *those* signed out the moment this
-     * resolves; if your app does not already make that consequence visible
-     * before they confirm, they will find out from a support ticket instead
-     * of from you.
+     * Changes the current app user's password.
+     *
+     * `currentPassword` is required even though the session already proves
+     * identity — it is what stops a stolen *session* from becoming a stolen
+     * *account*.
+     *
+     * **Every other session of this identity is revoked, and this call's own
+     * session is re-issued rather than spared.** The request carries nothing
+     * identifying the caller's own refresh family, so the server revokes all of
+     * them and hands back a fresh pair, which this method stores exactly like
+     * `login`. A user with other tabs or devices signed in will see those signed
+     * out the moment this resolves; if your app does not make that consequence
+     * visible before they confirm, they will find out from a support ticket.
      */
     changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /** Asks for a reset link. Resolves on `202` for a known and an unknown address alike — the answer says nothing about which it was. */
+    requestPasswordReset(email: string): Promise<void>;
+    /**
+     * Spends a reset token, sets the new password and **stores the session it
+     * answers with**. Every refresh family of that user is revoked first — a
+     * forgotten password is one of the two states where somebody else may be
+     * holding a session.
+     */
+    confirmPasswordReset(token: string, newPassword: string): Promise<void>;
+    /**
+     * Accepts an app invitation: creates the account (or activates one invited
+     * before it existed) with the role the invitation fixed, and **stores the
+     * session**.
+     *
+     * An invitation always bypasses the app's domain whitelist — a developer
+     * inviting somebody by hand has already made the decision the whitelist
+     * automates.
+     */
+    acceptInvitation(input: AcceptInvitationOptions): Promise<void>;
+    /**
+     * The app's **enabled** sign-in providers, for drawing the buttons on your
+     * own login screen. A disabled provider is not a button that refuses; it is a
+     * button that is not there.
+     *
+     * Public and unauthenticated, and it carries nothing but `slug` and `name` on
+     * purpose: the issuer, the client id, the scopes and the linking policy are
+     * management-side facts that would tell a stranger how the app's federation
+     * is configured.
+     */
+    listProviders(): Promise<ProviderButton[]>;
+    /**
+     * Builds the URL that starts a federated sign-in, with a fresh `state` and a
+     * fresh PKCE verifier. **Makes no network call and does not navigate** —
+     * persist `state` and `codeVerifier`, then send the browser to `url`.
+     *
+     * Nothing about the app, the provider or the redirect URI is validated here;
+     * it is all checked when the browser actually reaches the route, in that
+     * order, with the redirect target checked before the provider so that a
+     * caller who got the target wrong learns nothing about which providers the
+     * app has.
+     *
+     * Async only because the S256 `code_challenge` needs `crypto.subtle.digest`,
+     * which the Web Crypto API only ever offers as a promise.
+     */
+    beginOidcLogin(input: BeginOidcLoginOptions): Promise<OidcLoginRequest>;
+    /**
+     * Completes a federated sign-in: checks `state` against `expectedState`,
+     * trades the one-time `code` for a session, and stores it.
+     *
+     * **The state check runs before any request is sent.** RFC 6749 §10.12's
+     * whole point is that a client must not complete an authorization response it
+     * did not itself request — a check made after the exchange would already have
+     * spent a code for a flow this client never started. Both an outright
+     * mismatch and an *empty* `expectedState` throw `state_mismatch`; the message
+     * says which, because the remedies differ ("check how your app persisted the
+     * value" versus "this response belongs to a sign-in you did not start") even
+     * though the next step is the same either way — start the sign-in again.
+     *
+     * The code lives 60 seconds and is single-use. Unknown, expired, replayed and
+     * "the account was blocked in between" all arrive as one `token_spent`,
+     * because the app has nothing different to do about any of them.
+     */
+    completeOidcLogin(input: CompleteOidcLoginOptions): Promise<void>;
+    /**
+     * Reads a **failed** federated sign-in off the redirect back, as a
+     * `FleetlessError` you can branch on, or `null` when the callback carries no
+     * `error` at all.
+     *
+     * Fleetless renders no page for these: the reason is carried to your own
+     * `redirectUri` as `?error=<code>`, and this turns that string into the same
+     * error type every other method throws. A code the contracts define (see
+     * `ClientOidcErrorCode`) becomes that code verbatim; anything else becomes
+     * `unexpected_response` with the raw value in the message, rather than being
+     * passed through as a code neither side defines.
+     *
+     * Purely local — it parses a query string and asks nothing.
+     */
+    oidcErrorFromCallback(params: URLSearchParams): FleetlessError | null;
+    /**
+     * Reads a pending MCP authorization by the interaction id the browser
+     * arrived with, so the app can render its own consent screen.
+     *
+     * **`client_name` is a string the client typed about itself** during an
+     * unauthenticated dynamic registration — nobody checked it, which is why
+     * `client_name_verified` is the literal `false` rather than a boolean with a
+     * `true` branch that could never happen. Do not render it as an identity.
+     *
+     * `interaction_expired` means exactly that: ten minutes ran out, or the id
+     * was never real. Both answer the same way, so the screen to show is "that
+     * took too long, start again" rather than an error.
+     *
+     * **Call this with the app user already signed in.** The route needs no
+     * credential, but it reads one if present, and `already_granted` is `false`
+     * for an anonymous read whatever the truth is — so a consent screen rendered
+     * from an unauthenticated call asks a person to agree to something they
+     * agreed to already. An **expired** token counts as anonymous to this route,
+     * which answers `200` rather than refusing, so this method probes the
+     * session's liveness first and refreshes if it can; a session that cannot be
+     * refreshed is not an error here, it is genuinely anonymous.
+     */
+    mcpInteraction(id: string): Promise<ClientMcpInteraction>;
+    /** Approves a pending MCP authorization on behalf of the signed-in app user, and returns where to send the browser. */
+    approveMcpInteraction(id: string): Promise<McpInteractionDecision>;
+    /** Denies one. Also returns a redirect — with `error=access_denied` on it, so the client learns from its own callback. */
+    denyMcpInteraction(id: string): Promise<McpInteractionDecision>;
+    /**
+     * Every MCP client this app user has standing consent for — the "connected
+     * apps" list, and the door out of a decision a person could otherwise make
+     * once and never unmake. A withdrawn grant is never listed.
+     *
+     * `client_name_verified` is `false` here for the reason it is on
+     * `mcpInteraction`, and it matters more rather than less: a list like this is
+     * read long after the moment of approval, when nobody remembers what they
+     * clicked.
+     */
+    listMcpGrants(): Promise<McpConsentGrant[]>;
     /**
-     * The hosted password-reset page, served by the platform on the API
-     * origin (`/reset-password`). An app links a user there; nothing is
-     * called. The two former methods that posted to `/api/client/password/…`
-     * are gone with the routes they named (2.0.0).
-     *
-     * The page owns the whole flow — it takes the address, mails a
-     * single-use link, and takes the new password on the way back — so there
-     * is nothing for an app to sequence and nothing here that could reveal
-     * whether an address belongs to an account.
+     * Withdraws one standing consent by the client's id.
+     *
+     * Resolves whether or not there was anything to withdraw — a client id this
+     * account never approved and one it withdrew a minute ago both land on the
+     * end state the caller asked for. A refusal there would tell a caller which
+     * clients an account has connected, and would turn a double-clicked button
+     * into a failure.
      */
-    passwordResetUrl(): string;
+    revokeMcpGrant(clientId: string): Promise<void>;
 }
 
 /**
@@ -1937,58 +1879,6 @@ interface DatapointsApi {
     }): Promise<HistorySamplesResponse>;
 }
 
-/**
- * An end user's own consent grants, reachable as `client.grants` — every
- * client this identity has ever authorized, and the means to take one back
- * without touching any of the others.
- *
- * **End-user only.** A server key acts with the app's own full rights and
- * never went through a consent screen itself — there is no "self" here for
- * it to list or revoke, same reasoning as `auth.login` on a `serverKey`
- * client. An end user reaches a group by invitation and signs in through
- * `auth.login` or the hosted login; a server key never does either.
- */
-interface GrantsApi {
-    /**
-     * Every client this end user has consented to, most-recently-granted
-     * first. Each entry carries names, not only ids (`client_name`, `app_name`,
-     * `role_name`) — the id is what `revoke()` addresses, but a person
-     * deciding whether to revoke something needs to *recognise* it first, and
-     * an id is not recognisable. **`client_name` is not trusted** — a
-     * self-registered client chooses its own display name, and one has
-     * already been measured calling itself "Fleetless Official Helper" — do
-     * not render it as if Fleetless vouched for it.
-     */
-    list(): Promise<ConsentGrantSummary[]>;
-    /**
-     * Revokes one grant by the client's id — the `client_id` from a
-     * `list()` entry — without touching any other client's access.
-     *
-     * `revoked` tells "nothing matched" (`false`) from "matched and ended"
-     * (`true`) — revoking a grant that is already gone (a stale id, a double
-     * click) is not an error, just a no-op the caller can still tell apart
-     * from a real revocation. `tokens_revoked` counts refresh **families**
-     * ended, not access tokens — that count is deliberately never a claim
-     * about access tokens, which are stateless and short-lived by design.
-     *
-     * **What actually happens to an already-issued access token is stronger
-     * than that count implies.** It does not simply expire on its own: the
-     * cloud re-checks
-     * every request for a revoked grant, so **any** currently-valid access
-     * token minted through this same client's OAuth flow for this end user
-     * — not only the one used to call `revoke()` — answers `401
-     * token_revoked` on its very next request, no wait for its TTL. This is
-     * scoped to that one client: a session that never went through this
-     * client's consent (a plain `auth.login()` session, or one bound to a
-     * different client) carries no trace of this client's id and is
-     * unaffected. Do not build on the weaker "it will expire eventually" —
-     * if this platform ever moves to stateless verification without that
-     * re-check, this immediacy would go away silently, which is exactly why
-     * it is written down here instead of left implied.
-     */
-    revoke(clientId: string): Promise<ConsentRevokeResponse>;
-}
-
 /**
  * Robot-wide job reads, reachable as `client.jobs`. Everything here is
  * addressed by robot rather than by slug, which is what `actions` and
@@ -2142,10 +2032,12 @@ interface FleetlessClientConfig {
 interface FleetlessClient {
     /** The settled configuration, including the defaults `createClient` filled in. */
     readonly config: FleetlessClientConfig;
-    /** Logging in, logging out, and reading who the caller currently is. */
+    /**
+     * The whole client auth API: registration, verification, login, logout,
+     * password reset, invitations, the app's federated sign-in providers, the
+     * MCP consent screen, and the app user's own standing MCP grants.
+     */
     readonly auth: AuthApi;
-    /** An end user's own consent grants — not available on a `serverKey` client, same reasoning as `auth`'s session-only methods. */
-    readonly grants: GrantsApi;
     /** A topic's latest value, a live subscription to it, and its recorded history. */
     readonly datapoints: DatapointsApi;
     /** Long-running work on the robot: invoke, cancel, and watch a job as it runs. */
@@ -2176,8 +2068,8 @@ interface FleetlessClient {
 }
 /**
  * Builds a client for one app. Pass `tokenStore` (or nothing — the default
- * keeps the session in memory) for an end-user client that logs in with
- * `auth.login` or the hosted login; pass `serverKey` for a server-side
+ * keeps the session in memory) for an app-user client that signs in with
+ * `auth.login` or a federated provider; pass `serverKey` for a server-side
  * caller that never holds a user session. Passing both throws, because the
  * two are different identities and a client acts as exactly one.
  *
@@ -2186,4 +2078,4 @@ interface FleetlessClient {
  */
 declare function createClient(options: FleetlessClientOptions): FleetlessClient;
 
-export { type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginHostedLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type CompleteHostedLoginOptions, type ConsentGrantSummary, type ConsentRevokeResponse, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type GrantsApi, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, type HostedLoginRequest, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type LogoutResult, type MeshLoaderDelegate, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type PublishersApi, type RateLimitDetails, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };
+export { type AcceptInvitationOptions, type ActionsApi, type Asset, type AssetBytes, type AssetListResponse, type AssetsApi, type AuthApi, type BeginOidcLoginOptions, type BusyDetails, type CameraDescriptor, type CameraLiveSession, type CameraSnapshot, type CameraSnapshotMeta, type CamerasApi, type ClientIdentity, type ClientMcpInteraction, type ClientOidcErrorCode, type CompleteOidcLoginOptions, type CreateMeshLoaderOptions, type DatapointEvent, type DatapointSubscription, type DatapointSubscriptionHandlers, type DatapointValue, type DatapointsApi, type FleetlessClient, type FleetlessClientConfig, type FleetlessClientOptions, FleetlessError, type FleetlessErrorCode, type FleetlessErrorOptions, type HistoryAggregation, type HistoryBucketsResponse, type HistoryOptions, type HistorySamplesResponse, InMemoryTokenStore, type InvokeOptions, type Job, type JobEvent, type JobState, type JobSubscription, type JobSubscriptionHandlers, type JobsApi, type McpConsentGrant, type McpInteractionDecision, type MeshLoaderDelegate, type OidcLoginRequest, type ParameterInvalidDetails, type ParameterViolation, type PrepareUrdfSceneOptions, type ProviderButton, type PublishersApi, type RateLimitDetails, type RegisterOptions, SDK_ERROR_CODES, type SdkErrorCode, type SendCommandOptions, type ServicesApi, type StoredSession, type TokenStore, type UrdfCompleteness, type UrdfSceneManager, type UrdfSceneResources, createClient, parameterInvalidDetails };