@fleetless/sdk 3.0.0 → 3.0.2

package/RELEASING.md

@@ -0,0 +1,195 @@
+# Releasing `@fleetless/sdk`
+
+Maintainer notes: the development setup, the checks, and the release
+procedure. This file is not part of the published package.
+
+**CI runs on GitLab; the repository will mirror to GitHub.** The pipeline
+that verifies and publishes this package lives on an internal GitLab instance,
+and that is the only thing that publishes to npm. The public repository does not
+exist yet; when it does it is a mirror, where issues and pull requests arrive
+and no check runs. A contributor's pull request is verified by a maintainer
+running the same commands locally — see
+[CONTRIBUTING.md](CONTRIBUTING.md), which says so to the contributor as well.
+
+A mirror pushes what it is given, so **everything in a commit becomes public
+the moment it is pushed**, including the commit message and every file the
+branch touched.
+## Development setup
+
+Node 22 via `nvm`, and pnpm through corepack:
+
+```sh
+nvm use 22
+corepack enable
+pnpm install
+```
+
+**That install needs nothing private.** `@fleetless/contracts` — the source
+of truth for every wire type this SDK reads or writes — is a devDependency on
+the public npm package, pinned to an exact version. It used to be a private
+`git+ssh://` URL that only somebody with GitLab group access could install;
+that is over. The published SDK is unaffected either way: `tsup` inlines
+contracts' types into `dist/`, so a consumer of `@fleetless/sdk` never
+resolves it.
+
+Never redefine a shape the SDK sends to or reads from the API. Import it from
+`@fleetless/contracts` instead.
+
+## Checks
+
+| Command | What it does |
+|---|---|
+| `pnpm typecheck` | `tsc --noEmit` over the package. |
+| `pnpm test` | vitest. Most suites drive a fake `fetch` and a fake WebSocket; the three auth suites drive the SDK's own default `fetch` against a real `node:http` server (`test/local-api.ts`). No cloud needed. |
+| `pnpm build` | tsup into `dist/` — ESM, CJS and `.d.ts`. |
+| `pnpm run test:pack` | `npm pack`s the tarball, installs it into a bare project with nothing but `typescript`, and typechecks and runs real usage against it. This is what catches a `dist/index.d.ts` that still imports from `@fleetless/contracts` — a devDependency, so a consumer of the SDK never installs it. |
+
+Two further scripts check the built package against a **running** cloud
+(`./infra/dev.sh` in the umbrella repo). Each one runs against `dist/`, not
+`src/`, so run `pnpm build` first, and each fails by name on a missing
+variable rather than defaulting quietly.
+
+- `pnpm run verify:live` — a `busy` refusal carrying the job that is already
+  running, `command_outcome_unknown` and its documented recovery, a
+  `parameter_invalid` naming the flat key, job-id-addressed cancel, and
+  per-session camera release. Needs `FLEETLESS_API_URL` (or `API`),
+  `APP_IDENTIFIER`, `EMAIL`, `PASSWORD`, `ROBOT_ID`, `ACTION_SLUG`,
+  `SERVICE_SLUG`, `CAMERA_SLUG`, and two optional identities:
+  - `SECOND_EMAIL` — a second, distinct **app user** with the same role,
+    without which the busy check only proves that a second request is refused,
+    not that a different user's is.
+  - `OBSERVER_EMAIL` — a **third** app user, and the one whose password check
+    [6] rotates and restores. Leave it unset and the round trip runs on
+    `EMAIL`, the identity every other check in the file signs in as; the
+    script says so out loud when that happens. `infra/seed-dev.mjs --env`
+    exports all three.
+
+  Since 3.0.0 it also drives the client auth API as check [6]: `listProviders`
+  without a session, `login`, `me` (kind, app, role, address), `logout`, the
+  `changePassword` round trip with its restore, and the reset acknowledgement
+  compared byte for byte across a known and an unknown address. What it does
+  **not** drive is anything needing a mailed token — `register`,
+  `verifyEmail`, `acceptInvitation`, `confirmPasswordReset` — or the federated
+  and MCP-consent flows. Those are `infra/browser/app-auth-check.mjs`'s
+  subject, which reads maildev and drives a real Keycloak.
+- `pnpm run verify:history` — a relative range and its absolute equivalent
+  returning the same samples, aggregation matching arithmetic done here from
+  the raw rows, and the `not_recorded` / `not_aggregatable` refusals. Needs
+  `FLEETLESS_API_URL`, `APP_IDENTIFIER`, `EMAIL`, `PASSWORD`, `ROBOT_ID`,
+  `RECORDED_NUMERIC_SLUG`, `LIVE_ONLY_SLUG`, and optionally
+  `NON_NUMERIC_RECORDED_SLUG`.
+(`verify:hosted-login` is gone. The hosted login flow it drove —
+`beginHostedLogin` / `completeHostedLogin` and the app OAuth client behind
+them — was removed in 3.0.0 along with the script and its `package.json`
+entry.)
+
+`infra/seed-dev.mjs --env` in the umbrella repo exports most of those
+variables for a freshly seeded world.
+
+## Commits
+
+[Conventional Commits](https://www.conventionalcommits.org/). English, for
+code, comments, commit messages and everything else that lands in the
+repository.
+
+## Releasing
+
+Every version on npm is published by this repository's GitLab pipeline from a
+release tag. `npm publish` by hand is retired.
+
+1. Add the version's entry to `CHANGELOG.md` and set `version` in
+   `package.json` to the same number.
+2. Commit (`chore(release): X.Y.Z`), push, and wait for the branch pipeline's
+   `verify` job to go green.
+3. `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag pipeline runs `verify`
+   again and then `publish`.
+4. Check the registry yourself. The `publish` job already asserts the first
+   line; this is the independent look, and the second line is the one that
+   says which dist-tag moved.
+
+   ```sh
+   npm view @fleetless/sdk@X.Y.Z version   # answers X.Y.Z
+   npm view @fleetless/sdk dist-tags       # latest -> X.Y.Z, or next -> X.Y.Z
+   ```
+
+   Name the version. A bare `npm view @fleetless/sdk version` resolves the
+   `latest` dist-tag, so after a pre-release publish it answers the *previous*
+   stable release and reads as a publish that did not happen.
+
+A pre-release tag — `vX.Y.Z-beta.1`, `vX.Y.Z-rc.2` — publishes under the npm
+dist-tag `next` instead of `latest`. Nothing else about it differs, and it is
+exactly why step 4 names the version.
+
+**A red `publish` job does not mean nothing was published.** The job runs
+`npm publish` and then looks the version up on the registry for about two
+minutes; npm answers reads from a replica that lags a publish, so the lookup
+can time out on a version that did land. The job says so itself, and it is
+worth repeating here because a red pipeline invites exactly one reaction —
+press retry — and that reaction cannot work: npm refuses to publish over an
+existing version, so the retry ends in a 403 that reads like a broken
+pipeline rather than like a release that already happened.
+
+> publish may have succeeded; the registry has not served the version yet; do
+> NOT retry this job (npm refuses to republish a version) — check
+> `npm view @fleetless/sdk@$VERSION` by hand
+
+If the hand check answers the version, the release is done: move the dist-tag
+by hand if it is wrong (`npm dist-tag add @fleetless/sdk@X.Y.Z latest`) and
+leave the job red. If it answers nothing after several minutes, the publish
+genuinely did not land and the job can be retried.
+
+**A red `publish` job that ends in `npm error code EOTP` published nothing.**
+npm is asking for a one-time password, which a pipeline cannot supply: the
+token in `NPM_TOKEN` does not bypass two-factor authentication, or the
+package's *Publishing access* setting on npmjs.com disallows tokens. Fix the
+token (a granular access token created with *Bypass two-factor
+authentication*) or the package setting (*Require two-factor authentication
+or an automation token*), then retry the job — nothing reached the registry,
+so a retry is safe here — measured on a pipeline that hit it.
+
+**The pipeline refuses a tag whose version disagrees with `package.json`.**
+`scripts/verify-version-tag.mjs` is the one place that rule lives; `verify`
+runs it first on a tag pipeline, so a mistyped tag fails in seconds and
+`publish` never starts (measured: `verify-version-tag: tag v9.9.9 names
+9.9.9 but package.json says 1.0.0`, publish skipped).
+
+Removing that bad tag takes the API, not git. `v*` is a **protected** tag
+pattern, so a delete over git is refused by the server with nothing but
+`! [remote rejected] v9.9.9 (pre-receive hook declined)`:
+
+```sh
+git tag -d vX.Y.Z                                          # local
+glab api -X DELETE projects/37/repository/tags/vX.Y.Z      # remote
+```
+
+Then fix `package.json` and tag again.
+
+### The one-time setting
+
+It is already in place; it is written down because nothing in this repository
+would tell you it exists if it were removed.
+
+There used to be a second one — `fleetless/fleetless-sdk` on the job-token
+allow-list of `fleetless/fleetless-contracts`, so the pipeline could rewrite
+the private `git+ssh://` contracts URL to HTTPS with `CI_JOB_TOKEN`. Contracts
+is a public npm package now, the rewrite is gone from `.gitlab-ci.yml`, and
+the allow-list entry buys this project nothing. Removing it is safe; leaving
+it is harmless.
+
+- **`NPM_TOKEN` is a protected, masked CI variable on this project**, holding
+  an npm granular automation token with publish rights on `@fleetless/sdk`.
+  Protected means an unprotected ref receives an *empty* value rather than no
+  value, which is why the tag pattern `v*` is a protected tag and why the
+  `publish` job's first action is to refuse an empty `NPM_TOKEN` by name.
+
+  ```sh
+  glab api projects/37/protected_tags     # v*, create access: Maintainers
+  ```
+
+The token reaches npm through an `.npmrc` written in the job's working
+directory holding `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` **literally**
+— npm expands the variable when it reads the file, so the secret itself never
+lands on disk, and `after_script` removes the file either way. It cannot be
+passed as an environment assignment instead: `NPM_CONFIG_//registry…` is not a
+valid shell identifier, so both `bash` and `dash` parse it as a command name.
+

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.