@fleetless/sdk 2.1.0 → 3.0.1

package/README.md

@@ -9,12 +9,27 @@ The official TypeScript SDK for apps built on [Fleetless](https://fleetless.dev)
 which exposes a ROS 2 robot as a hosted REST and realtime API — exactly the
 topics, services and actions a developer chose to publish, under stable slugs,
 behind roles. The SDK covers all of it: datapoints (read, subscribe, recorded
-history), actions, services, publishers, cameras, jobs, assets and URDF, the
-hosted login, and an end user's own consent grants. It is framework-agnostic,
+history), actions, services, publishers, cameras, jobs, assets and URDF, and
+the whole client auth API your own sign-in UI calls. It is framework-agnostic,
 ships ESM and CJS with its own types, and runs wherever a `fetch` and a
 `WebSocket` exist — a browser, a mobile webview, Node 20 or newer, and
 server-side with a server key instead of a user session.
 
+**The mental model in one paragraph.** A robot runs the Fleetless bridge, a
+ROS 2 node. In the [Fleetless Console](https://console.fleetless.dev) a
+developer picks which topics, services and actions that robot exposes and gives
+each one a stable `snake_case` slug and a role that may reach it. The cloud
+turns those into REST and realtime endpoints. This package is the client for
+those endpoints: you address a robot by its id and a capability by its slug,
+you sign your own users in against your own app's user directory, and you never
+see a ROS name, a topic type or a message definition. Renaming a node on the
+robot is invisible to your app; changing a slug is not.
+
+New here? The [getting-started guide](https://docs.fleetless.dev/getting-started/)
+goes from a robot that has never connected to a value on a page, and the
+[app-auth recipe](https://docs.fleetless.dev/recipes/app-auth/) is the
+walkthrough for every sign-in screen.
+
 ## Why
 
 - **One connection, however many subscriptions.** Every datapoint and job
@@ -40,11 +55,13 @@ server-side with a server key instead of a user session.
   `cameras.live` takes a refcounted hold: the first viewer starts the robot
   publishing, the last one leaving stops it. You get a LiveKit room URL and
   token to hand to the LiveKit client of your choice.
-- **Hosted login, so your app never handles a password.** OAuth 2.1
-  Authorization Code with PKCE (S256 only). `beginHostedLogin` makes no network
-  call at all, and `completeHostedLogin` checks `state` before it exchanges
-  anything. Federation to a customer's identity provider happens on the hosted
-  page, not in your code.
+- **The whole auth surface, and every screen stays yours.** Fleetless renders
+  no page for an app user: registration with email verification, invitations,
+  password reset, single sign-on to one of the app's identity providers, and
+  the MCP consent screen are all methods on `client.auth`, called from a UI you
+  wrote. The federated flow runs its own PKCE (S256 only) against Fleetless;
+  `beginOidcLogin` makes no network call, and `completeOidcLogin` checks
+  `state` before it exchanges anything.
 - **A token store you control.** Implement two methods to keep a session in
   `localStorage`, a cookie or a native keystore; the default keeps it in
   memory. Refresh is silent and single-flight, so ten concurrent calls that
@@ -56,8 +73,10 @@ server-side with a server key instead of a user session.
 npm i @fleetless/sdk
 ```
 
-You need an app identifier and an end user's credentials from the
-[Fleetless Console](https://console.fleetless.dev).
+You need an app identifier and the credentials of an **app user** — an
+account inside that app, which the developer's team creates or invites from
+the [Fleetless Console](https://console.fleetless.dev). A console login is a
+Fleetless user, a different identity space, and will not sign in here.
 
 ```ts checked
 import { createClient } from '@fleetless/sdk'
@@ -98,45 +117,107 @@ Slugs are the names you chose in the console, in `snake_case`
 (`[a-z][a-z0-9]*(_[a-z0-9]+)*`) — never the robot's internal ROS names, which
 is what makes renaming a node on the robot invisible to your app.
 
-### Hosted login
+### Your own sign-in UI
+
+Every screen an app user sees belongs to your app. These are the calls behind
+them; the full walkthrough, page by page, is the
+[app-auth recipe](https://docs.fleetless.dev/recipes/app-auth/).
+
+```ts
+// Registration. Resolves on 202 — which says a policy-allowed request was
+// accepted, NOT that an account was created. An address the app already knows
+// gets the identical answer with no mail sent, so the only honest thing to
+// render is a sentence about the mailbox.
+await client.auth.register({ email, password, displayName })
+
+// The page your app serves at the app's configured `verify_url`. Stores a
+// session, so nobody types a password right after reading their mail.
+await client.auth.verifyEmail(tokenFromTheLink)
+
+// Recovery. requestPasswordReset always resolves on 202, for a known address
+// and an unknown one alike.
+await client.auth.requestPasswordReset(email)
+await client.auth.confirmPasswordReset(tokenFromTheLink, newPassword)
+
+// The page your app serves at the app's configured `invite_url`.
+await client.auth.acceptInvitation({ token: tokenFromTheLink, password })
+```
+
+### Sign-in through an identity provider
 
-Redirect the end user to the Fleetless-hosted login page instead of collecting
-a password yourself. Register the OAuth client in the console first, under
-**App Settings → OAuth clients**; its `client_id` is not your `appIdentifier`.
+An app may carry any number of OpenID Connect providers, configured per app in
+the console. Your page draws the buttons; your app never talks to the provider.
 
 ```ts
-// 1. Build the URL. No network call happens here.
-const request = await client.auth.beginHostedLogin({
-  clientId: 'oauth-client-id-from-the-console',
+// Draw the buttons. Only enabled providers are listed, slug and name only.
+const providers = await client.auth.listProviders()
+
+// 1. Build the URL. No network call: this generates the PKCE verifier and the
+//    state, and hands them back, because a redirect is a fresh page load.
+const request = await client.auth.beginOidcLogin({
+  slug: 'azure',
   redirectUri: 'https://your-app.example.com/callback',
 })
-
-// A redirect is a fresh page load, so persist these two yourself.
 sessionStorage.setItem('fleetless_state', request.state)
 sessionStorage.setItem('fleetless_code_verifier', request.codeVerifier)
-window.location.href = request.url
-
-// 2. On the callback page. The callback can legitimately carry ?error=...
-//    instead of a code, so check for that first.
-const params = new URLSearchParams(window.location.search)
-const expectedState = sessionStorage.getItem('fleetless_state')
-const codeVerifier = sessionStorage.getItem('fleetless_code_verifier')
-
-if (!params.has('error') && expectedState && codeVerifier) {
-  await client.auth.completeHostedLogin({
+window.location.assign(request.url)
+
+// 2. On the callback page. A refused sign-in redirects here with `error`
+//    rather than a code, so check for that first.
+const params = new URL(window.location.href).searchParams
+const failure = client.auth.oidcErrorFromCallback(params)
+if (failure) {
+  // A FleetlessError carrying the documented reason: no_access, email_taken,
+  // email_unverified, domain_not_allowed, registration_closed, and the rest.
+  showSignInProblem(failure)
+} else {
+  await client.auth.completeOidcLogin({
     code: params.get('code') ?? '',
     state: params.get('state') ?? '',
-    expectedState,
-    codeVerifier,
-    clientId: 'oauth-client-id-from-the-console',
-    redirectUri: 'https://your-app.example.com/callback',
+    expectedState: sessionStorage.getItem('fleetless_state') ?? '',
+    codeVerifier: sessionStorage.getItem('fleetless_code_verifier') ?? '',
   })
   // From here on me(), logout() and silent refresh behave exactly as they do
-  // after login(). Never call completeHostedLogin twice for the same code.
+  // after login().
 }
 ```
 
-### Running a job
+`completeOidcLogin` refuses before any network call, with `state_mismatch`,
+for a mismatch, a missing `state`, **and** an empty `expectedState` — that
+last case is checked first and explicitly, because two empty strings compare
+equal.
+
+One callback URL is registered at the provider,
+`https://api.fleetless.dev/api/client/oidc/callback`, the same for every app
+and every provider. It is not your `redirectUri`, which is a page in your app.
+
+### The MCP consent screen
+
+Only if the app serves its own MCP endpoint. An authorization redirects the
+browser to a page your app serves, with an interaction id; your page signs the
+person in, shows them what is being asked, and answers.
+
+```ts
+// Sign the person in FIRST — `already_granted` is derived from the bearer,
+// and an anonymous read answers `false` for everybody.
+const interaction = await client.auth.mcpInteraction(interactionId)
+
+// `interaction.client_name` is a name the client typed about itself during an
+// unauthenticated registration. `client_name_verified` is the literal false;
+// render it as a claim, never as an identity. `scopes` is always empty: what a
+// session reaches is decided by the user's role, re-read on every call.
+const { redirectTo } = approved
+  ? await client.auth.approveMcpInteraction(interactionId)
+  : await client.auth.denyMcpInteraction(interactionId)
+window.location.assign(redirectTo) // a denial redirects too
+
+// A "connected apps" screen. Withdrawing stops the NEXT authorization; a
+// session already running keeps working for the rest of its 15 minutes.
+const grants = await client.auth.listMcpGrants()
+await client.auth.revokeMcpGrant(grants[0].client_id)
+```
+
+### Actions
 
 An action is a job with a lifecycle. `invoke` resolves as soon as the job
 exists; feedback, progress and the result arrive over `subscribe`.
@@ -164,6 +245,35 @@ sub.unsubscribe()
 `error.details.running`. A service is the same machinery with a plain result:
 `await client.services.call(robotId, 'set_mode', { mode: 'autonomous' })`.
 
+### Publishers, and no teleop helpers
+
+`publishers.publish` sends **one** message. There is no `startPublishing`, no
+rate helper, no joystick binding and no "hold this value" call, and that is a
+decision rather than a gap.
+
+The safety primitive lives on the robot. A publisher is configured with a
+`timeout_ms` and a failsafe message; if messages stop arriving — including
+because your process crashed, your tab closed, or the network went away — the
+bridge publishes the failsafe itself. Nothing in your event loop has to survive
+for that to happen.
+
+A helper here would move the appearance of that guarantee into a browser, where
+it is not true. So *how often* and *when* to publish is your application's
+decision, made where it can see the user's intent:
+
+```ts
+// A control loop is yours to write, and yours to stop.
+const timer = setInterval(() => {
+  void client.publishers.publish(robotId, 'cmd_vel', { 'linear.x': speed })
+}, 100)
+
+// Stop publishing and let the robot's own failsafe take over.
+clearInterval(timer)
+```
+
+`publish` rejects `publisher_busy` while a different user holds the publisher
+and has not been quiet for its configured timeout.
+
 ### Cameras
 
 ```ts
@@ -184,29 +294,43 @@ await room.disconnect()
 await session.release()
 ```
 
-## Migrating from 1.0.0
-
-2.0.0 is a breaking release. `CHANGELOG.md` carries the complete inventory —
-established by diffing the published 1.0.0 tarball's types against this one's,
-not read off the commit log. The breaks, one line each:
-
-- `auth.register()` and `auth.confirmRegistration()` are gone with no
-  successor; a group grows by invitation (see [Account recovery](https://docs.fleetless.dev/reference/sdk/#account-recovery) in the SDK reference).
-- `auth.requestPasswordReset()` and `auth.confirmPasswordReset()` are gone.
-  Link the user to `auth.passwordResetUrl()` instead.
-- The types `MailStatus` and `ClientRegisterResponse` went with them.
-- The error code `not_a_member` is gone — a compile break for an exhaustive
-  `switch` on `error.code`.
-- `CameraDescriptor.snapshot_interval_ms` is now `snapshot_interval_seconds`.
-  **Read that twice:** it is a rename *and* a unit change, so renaming the
-  property and nothing else leaves you with a number a thousand times too
-  small.
-- `UrdfCompleteness.missing` and `UrdfSceneResources.missing` are no longer
-  `string[]` but `{ uri, element }[]`, so a missing texture is no longer
-  reported as a missing mesh. For the old shape: `missing.map((m) => m.uri)`.
-
-Nothing else was removed or re-typed. `auth.logout()`'s result grew a field and
-gained a name (`LogoutResult`); `.revoked` is unchanged.
+## Errors
+
+Every refusal arrives as a `FleetlessError` with a stable `code`. Branch on the
+code; never parse the message, which is written for a developer reading a
+console and may change.
+
+```ts
+import { FleetlessError } from '@fleetless/sdk'
+
+try {
+  await client.actions.invoke(robotId, 'dock', {})
+} catch (error) {
+  if (!(error instanceof FleetlessError)) throw error
+  switch (error.code) {
+    case 'busy':          return showRunning(error.details?.running)
+    case 'robot_offline': return showOffline()
+    case 'forbidden':     return showNotAllowed()
+    case 'rate_limited':  return showRetryLater(error.details?.retry_after_ms)
+    default:              return showUnexpected(error)
+  }
+}
+```
+
+- **`rate_limited` is surfaced, never retried behind your back.** The SDK does
+  not sleep and re-send. `error.details.retry_after_ms` carries the wait the
+  platform asked for, when it sent one — read it defensively, since a refusal
+  from an intermediary may carry no `details` at all.
+- **The one retry the SDK does perform is `token_expired`**, and only once: it
+  refreshes the session and re-sends the same request. That refresh is
+  single-flight, so ten concurrent calls meeting an expired token share one.
+- **`command_outcome_unknown` is an honest answer, not a failure.** It means
+  the realtime connection cycled while a command was in flight and the SDK
+  cannot say whether the robot got it. Read the job back by slug through
+  `actions.subscribe` to find out.
+- Some codes never reach the network at all — `invalid_option`,
+  `state_mismatch`, `no_session`, `untrusted_absolute_url`. They are the SDK
+  refusing to send something rather than the platform refusing to accept it.
 
 ## Documentation and help
 
@@ -216,18 +340,38 @@ gained a name (`LogoutResult`); `.revoked` is unchanged.
   robot that has never connected to a value in your app.
 - **[REST and realtime API](https://docs.fleetless.dev/reference/api/)** — the
   wire surface underneath this package.
-- **[Hosted login recipe](https://docs.fleetless.dev/recipes/hosted-login/)** —
-  the full walkthrough, including every error the callback can carry.
+- **[Your own login UI](https://docs.fleetless.dev/recipes/app-auth/)** — the
+  full walkthrough for every auth screen, and the mistakes that cost the most
+  time.
+- **[Identity](https://docs.fleetless.dev/reference/identity/)** — the two
+  identity spaces, the federation rules, and what each refusal licenses your
+  UI to claim.
 - **[CHANGELOG.md](CHANGELOG.md)** — what changed in each version.
 - Questions, bug reports and feature requests: hello@fleetless.dev.
 
 Fleetless is in closed beta. The waiting list is at
 <https://fleetless.dev/#waiting-list>.
 
+## Reporting a security issue
+
+Email **security@fleetless.dev**. Please do not open a public issue for a
+security report. [SECURITY.md](SECURITY.md) says what is in scope here — how
+this package handles tokens, the PKCE verifier and the `state` value — and what
+belongs to the platform instead.
+
+## Contributing
+
+Pull requests are welcome at <https://github.com/fleetless/sdk>. Read
+[CONTRIBUTING.md](CONTRIBUTING.md) first: it covers the setup, the checks, the
+Contributor Licence Agreement, and the one rule this repository is strict about
+— the auth suites drive the SDK's own `fetch` against a real `node:http`
+server rather than a double, because a mocked `fetch` cannot see the bugs that
+have actually shipped.
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
 ## Maintainers
 
-Maintained by [Dehne Robotik GmbH](https://dehne-robotik.de). The source
-repository is private and takes no outside contributions; questions and bug
-reports go to hello@fleetless.dev.
+Maintained by [Dehne Robotik GmbH](https://dehne-robotik.de).
 
 MIT licensed — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,100 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Email **security@fleetless.dev**. Please do not open a public GitHub issue for
+a security report.
+
+Include what you found, the SDK version and runtime it happens on (a browser
+name and version, or a Node version), and the smallest sequence of SDK calls
+that shows it. A reproduction against a published version of this package is
+the most useful thing you can send.
+
+We acknowledge every report within **3 working days** and follow up with
+either a fix or a written plan within **30 days**. If a report leads to a
+released fix, we credit you by name unless you ask us not to.
+
+## What is in scope
+
+This repository is the TypeScript SDK that client applications use to talk to
+Fleetless. It runs **in your users' browsers and on your servers**, and it
+holds credentials while it does. That is where its security surface is.
+
+Specifically in scope:
+
+### Tokens
+
+The SDK receives an access token and a refresh token from the platform and
+hands them to a `TokenStore` that **you** implement; the built-in default keeps
+them in memory only and writes them nowhere. A report is in scope if the SDK:
+
+- puts a token somewhere the caller did not ask for it to go — a global, a
+  URL, a query string, a log line, an error message, or a thrown object's
+  properties;
+- sends a token to an origin other than the `apiUrl` the client was
+  constructed with;
+- attaches a token to a request it should not have (the SDK refuses an
+  absolute URL it did not build — see `untrusted_absolute_url`);
+- keeps a token reachable after `logout()`, or fails to clear the store;
+- races its own silent refresh in a way that lets a stale or a foreign token
+  be used.
+
+Choosing to persist tokens in `localStorage`, a cookie or a native keystore is
+your decision and its consequences are yours; a defect in how the SDK *hands*
+them to your store is ours.
+
+### PKCE and `state` in the federated sign-in flow
+
+`beginOidcLogin` generates a PKCE verifier and a `state` value and returns them
+to you, because a redirect is a fresh page load and the SDK has nowhere of its
+own to keep them. `completeOidcLogin` checks `state` before it exchanges
+anything.
+
+In scope: a verifier or a `state` with insufficient entropy or a predictable
+source; S256 not being enforced; `completeOidcLogin` exchanging a code when
+`state` does not match, is missing, or when `expectedState` is empty — that
+last case is checked first and explicitly, because two empty strings compare
+equal; any path that reaches the token exchange without the check.
+
+**Where you store the verifier and the `state` between the two calls is your
+application's decision**, and this policy cannot cover it. The README shows
+`sessionStorage`, which is a reasonable default and not the only correct one.
+
+### The rest of the package
+
+- Request construction: path segments are percent-encoded (`pathSegment`), so
+  a slug or an identifier shaped like `../../../admin` must not escape its
+  position in the URL.
+- The realtime channel: its authentication, its reconnection, and what it
+  resends after one.
+- `prepareUrdfScene` and `createMeshLoader`: a robot's own URDF names the URLs
+  three.js is asked to fetch, so a reference the SDK does not own must not
+  become a network request from your users' browsers.
+- Anything the SDK writes into browser-reachable state.
+- The published npm package `@fleetless/sdk` and its contents, including a
+  dependency of it.
+
+## What is not in scope
+
+**The Fleetless cloud is not in this repository.** A server that fails to
+enforce a permission, an authentication or authorisation flaw in the platform,
+a rate limit, a data leak from an API endpoint, anything about how a token is
+minted or validated — none of those live here, and none of them can be fixed by
+a change to this package. Report them to the same address; say which service
+you were looking at, and we will route it. What we cannot do is treat this
+repository's issue tracker as the place where they are tracked.
+
+Also out of scope here: the Fleetless console, the robot-side bridge, the
+`@fleetless/contracts` schemas (they have their own repository and their own
+policy), the documentation site, and any deployment of Fleetless operated by
+someone else.
+
+Out of scope in your own application: where you store tokens, how you protect
+your own pages, and any XSS in your app — an attacker who can run script in
+your page can read anything your page can, and no SDK design prevents that.
+
+## Supported versions
+
+The latest published minor of `@fleetless/sdk` receives fixes. Older minors do
+not; a security fix is released as a new patch on the current minor, and
+upgrading is the remedy.