Skip to content

Agent Mesh

docs: device enrollment guide

Antonio Ojea93fba683c046
diff --git a/mobile/sam-node-app/README.md b/mobile/sam-node-app/README.md
index c27656fb..e46d4d5b 100644
--- a/mobile/sam-node-app/README.md
+++ b/mobile/sam-node-app/README.md
@@ -60,12 +60,12 @@ flutter run
## How to Use the Application
-Once launched, the app displays a control interface:
+Once launched, the app (installed as **SAM Connect**, application id `dev.sammesh.connect`) asks you to enroll, then shows the dashboard:
-1. **Control plane URL**: The address of the SAM control plane (e.g., `https://bananas.sam-mesh.dev`).
-2. **Enrollment JWT**: A valid JWT token retrieved from your OIDC provider to authenticate the node registration.
+1. **Scan enrollment code**: The primary path. `sam-one` prints a single-use `sam://enroll?server=...&token=...` QR code at startup (and on demand with `sam-one token qr`); scan it, confirm the control plane hostname, and the app enrolls through `POST /enroll` with no identity provider involved. The phone's stock camera app can scan it too: the `sam://` link opens SAM Connect. Only `https://` control planes are accepted (plaintext `http://` for loopback only), because the control plane is the device's trust root. See [Device Enrollment](../../site/content/docs/user/device-enrollment.md).
+2. **Enter details manually**: Paste a whole `sam://enroll` link or a bare bootstrap token together with the **Control plane URL**, then **Join with token**. On a full control plane, mint the token with `POST /admin/bootstrap-tokens` (see `development/kind/run-local-node.sh`); on `sam-one`, `sam-one token create`. Below it, **Login & Enroll (Browser)** and **Device Login** are the OIDC alternatives: the app reads the issuer from the control plane's `/info` endpoint and opens a login.
3. **Local API Token**: The bearer token that secures the local sidecar REST API. It is generated on first launch and kept in the app's private storage; view, copy or regenerate it on the **Config** tab. There is no default: Android loopback is shared by every installed app, so a fixed value would let any of them act as this node.
-4. **Enroll Node**: Click this button first to generate the local Peer Identity and register the node with the control plane.
+4. **Labels**: Set on the **Config** tab *before* enrolling; they are attested into the node's Biscuit at that point.
5. **Start Node**: Launches the Go node runtime in the background. It will bind its local MCP sidecar to `127.0.0.1:5005`.
6. **Stop Node**: Gracefully shuts down the background Go mesh client.
@@ -98,7 +98,7 @@ Exposes capabilities directly to the OS registry, allowing native assistants (li
1. **Dashboard Tab**: Displays current status, Node ID, connected peers, and DHT size.
2. **Services Tab**: Allows enabling/disabling embedded sensors (Battery/Location) and bridging external local MCP servers.
-3. **Config Tab**: The node's labels and attenuation, the app's stand-in for `sam-node.yaml`. Labels (comma-separated `key=value`) are set here; the control plane attests them into the node's Biscuit at enrollment, so changing them later means pressing Re-enroll, which re-attests them with the login session saved at enrollment (the browser opens only if that session has expired) and keeps the node's identity. Attenuation is Datalog rules, policies and checks that limit who may call this node, one statement per line (e.g. `check if label("region", "eu-west-1");`). They are read when the node starts, and a syntax error fails the start. Same syntax and same errors as the `attenuation` block of `sam-node.yaml`; see [Node configuration §3](../../site/content/docs/user/node-configuration.md#3-defining-local-security-target-attenuation).
+3. **Config Tab**: The node's labels and attenuation, the app's stand-in for `sam-node.yaml`. Labels (comma-separated `key=value`) are set here; the control plane attests them into the node's Biscuit at enrollment, so changing them later means pressing Re-enroll, which re-attests them with the login session saved at enrollment (the browser opens only if that session has expired) and keeps the node's identity. A node that joined with a token or QR code has no login session and the control plane re-mints from the labels already on record, so Re-enroll is disabled for it: unenroll and join again with the new labels. Attenuation is Datalog rules, policies and checks that limit who may call this node, one statement per line (e.g. `check if label("region", "eu-west-1");`). They are read when the node starts, and a syntax error fails the start. Same syntax and same errors as the `attenuation` block of `sam-node.yaml`; see [Node configuration §3](../../site/content/docs/user/node-configuration.md#3-defining-local-security-target-attenuation).
---
diff --git a/site/content/docs/user/_index.md b/site/content/docs/user/_index.md
index 4b37c9eb..55528df0 100644
--- a/site/content/docs/user/_index.md
+++ b/site/content/docs/user/_index.md
@@ -22,3 +22,6 @@ Welcome to the User & Operator Guides. This section provides detailed documentat
5. **[SAM Mobile App](mobile-app/)**
Turn your mobile device into a SAM node, exposing sensors and telemetry securely to the mesh, and integrating with native OS assistants.
+
+6. **[Device Enrollment (QR Code)](device-enrollment/)**
+ Enroll phones by scanning a single-use `sam://enroll` code printed by `sam-one`, including publishing a laptop on a public https URL through a tunnel.
diff --git a/site/content/docs/user/cloud-run-deployment.md b/site/content/docs/user/cloud-run-deployment.md
index dfb1b1e7..3c041298 100644
--- a/site/content/docs/user/cloud-run-deployment.md
+++ b/site/content/docs/user/cloud-run-deployment.md
@@ -159,8 +159,12 @@ export SAM_ADMIN_TOKEN="$ADMIN_TOKEN"
# Mint a scoped, single-use enrollment token
sam-one token create --server "$URL" --role sam:role:node --max-usages 1
-# List tokens and their usage
+# Same, rendered as a QR code for the SAM mobile app (add --max-usages N for a room)
+sam-one token qr --server "$URL"
+
+# List tokens with their usage and status; revoke one by id prefix
sam-one token list --server "$URL"
+sam-one token revoke <token-id> --server "$URL"
# Ban a peer from the mesh
sam-one admin ban --server "$URL" <peer-id>
@@ -196,4 +200,6 @@ sam-one --data-dir /var/lib/sam-one
A free port is picked and published in the startup banner together with
the generated tokens; pass `--port 8080` (and optionally
`--bind-address`) for a fixed one, and `--external-url https://mesh.example.com`
-when fronted by a reverse proxy or DNS name.
+when fronted by a reverse proxy or DNS name. On a laptop behind NAT,
+`--tunnel cloudflare` publishes the port on a temporary public https URL
+instead; see [Device Enrollment](../device-enrollment/).
diff --git a/site/content/docs/user/device-enrollment.md b/site/content/docs/user/device-enrollment.md
new file mode 100644
index 00000000..ebaa91d8
--- /dev/null
+++ b/site/content/docs/user/device-enrollment.md
@@ -0,0 +1,173 @@
+---
+title: "Device Enrollment (QR Code)"
+linkTitle: "Device Enrollment"
+weight: 7
+---
+
+# Enrolling Phones with a QR Code
+
+A phone joins the mesh the same way a `sam-node` does: it presents a
+bootstrap token to the control plane's `POST /enroll`, which spends the
+token and issues the device a Biscuit bound to its own key. The only thing
+a QR code adds is a way to hand the phone the two facts it needs without
+typing them:
+
+```
+sam://enroll?server=<control-plane-url>&token=<bootstrap-token>
+```
+
+The token is an ordinary bootstrap token, so the code grants exactly what
+the token grants — one enrollment, in the token's role, until it expires —
+against any SAM control plane, `sam-one` or a full `sam-control-plane`.
+
+## 1. Run `sam-one` on a public https URL
+
+Phones only trust an **https** control plane (plaintext `http://` is
+accepted for loopback only): whoever answers that URL becomes the device's
+trust root, so `sam-one` refuses to draw a QR code for a plaintext address
+and tells you how to get one. Three ways, from a laptop to production:
+
+**Laptop behind NAT — a tunnel.** `sam-one` can publish its single port on
+a temporary public hostname through a tunnel provider. The first one is
+[Cloudflare Quick Tunnels](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/),
+which need no account:
+
+```bash
+sam-one --data-dir ~/sam-one --tunnel cloudflare
+```
+
+If `cloudflared` is not on your `PATH`, `sam-one` offers to download the
+pinned release from GitHub into `~/sam-one/bin`. The download is verified
+against a SHA-256 digest compiled into `sam-one`, re-verified before every
+launch, and only happens after you accept Cloudflare's license at the
+prompt (or pass `--tunnel-install` to accept up front, for scripts). Pass
+`--cloudflared-path` to use a copy you installed yourself.
+
+Quick tunnels are for testing and demos: no uptime guarantee, a new
+hostname on every start, and no Server-Sent Events. Everything else works —
+enrollment, the web console, and the `wss` mesh transport nodes use to
+reach the embedded router.
+
+**Cloud Run** terminates TLS for you; follow the
+[Cloud Run deployment guide](../cloud-run-deployment/) and set
+`SAM_EXTERNAL_URL` to the service URL.
+
+**Your own VM and domain — a reverse proxy.** Put an ACME-capable proxy in
+front of the single port and tell `sam-one` its public name:
+
+```bash
+# Caddyfile: Let's Encrypt certificate, automatic renewal, WebSockets included.
+mesh.example.com {
+ reverse_proxy 127.0.0.1:8080
+}
+
+sam-one --data-dir /var/lib/sam-one --port 8080 --external-url https://mesh.example.com
+```
+
+## 2. Read the code
+
+With a public https URL, `sam-one` prints a device enrollment block under
+its startup banner whenever stdout is a terminal (`--enroll-qr=false` to
+suppress it, `--enroll-qr` to force it):
+
+```
+Scan with the SAM app to enroll a device into brave-otter-quick-1234.trycloudflare.com
+(single use, valid for 1h0m0s):
+
+█████████████████████████████████████
+████ ▄▄▄▄▄ █▀ █▀▀▄▀▄▀▀ █ ▄▄▄▄▄ ████
+...
+
+sam://enroll?server=https%3A%2F%2Fbrave-otter-quick-1234.trycloudflare.com&token=sam_dev_...
+```
+
+Each code carries a fresh node token, minted for that boot and valid for
+one hour. By default it is **single use**: once a device has spent it,
+`POST /enroll` refuses it for anyone else. It is never persisted, so a
+stale screenshot is worthless.
+
+For more devices, or on a non-interactive deployment, mint a code on demand
+with the admin CLI:
+
+```bash
+export SAM_ADMIN_TOKEN=... # from the banner, or <data-dir>/admin-token
+sam-one token qr --server https://brave-otter-quick-1234.trycloudflare.com
+```
+
+`--server` is both where the CLI talks to and the URL embedded in the code;
+pass `--enroll-url https://...` when devices reach the mesh on a different
+address than the admin does. `sam-one token list` shows every minted token
+with its usage count and status, and the standard `--role`/`--ttl-hours`
+tokens from `sam-one token create` work in the app's manual entry too.
+
+### One code for a whole room
+
+A demo with an audience does not want one code per phone. Give the code a
+usage budget instead, and every device that scans it joins until the
+budget, the TTL or you say otherwise:
+
+```bash
+# Startup code good for 200 devices (projector-friendly).
+sam-one --data-dir ~/sam-one --tunnel cloudflare --enroll-qr-max-usages 200
+
+# Or mint one for the afternoon on a running mesh.
+sam-one token qr --server "$URL" --max-usages 200 --ttl-hours 4
+```
+
+The caption under the code says how many devices it admits and prints the
+token id. Anyone who photographs a shared code can enroll until it is
+exhausted, so end it when the session ends:
+
+```bash
+sam-one token list --server "$URL" # STATUS: active / exhausted / expired / revoked
+sam-one token revoke 9c75ab4a3122 --server "$URL"
+```
+
+Revoking a token stops further enrollments only; the devices it already
+admitted keep their identity. Remove one of those with
+`sam-one admin ban <peer-id>`, or, for a throwaway demo mesh, simply stop
+`sam-one` (a fresh data dir is a fresh mesh).
+
+On a full `sam-control-plane`, mint the token with
+`POST /admin/bootstrap-tokens` (`max_usages: 1`) and build the same
+`sam://enroll?...` string; the app does not care which binary is behind the
+URL.
+
+## 3. Enroll the phone
+
+In **SAM Connect** (the Android app):
+
+1. Tap **Scan enrollment code** and point the camera at the terminal. The
+ app only accepts `sam://enroll` codes; any other QR is ignored with a
+ hint.
+2. Confirm the control plane hostname in the dialog and tap **Join**. Labels
+ set on the **Config** tab are attested into the device's Biscuit at this
+ point.
+3. Start the node from the dashboard.
+
+Scanning with the phone's stock camera app works as well: the `sam://`
+link opens SAM Connect with the same confirmation dialog. **Enter details
+manually** covers everything else: paste the whole `sam://enroll` link or a
+bare token (with the control plane URL), or use the browser and device
+OIDC logins where the control plane is configured with an identity
+provider.
+
+A device that joined with a token has no login session to refresh, so its
+labels cannot be re-attested in place: **Re-enroll** is disabled for it,
+and changing labels means unenrolling and scanning a new code.
+
+## What the token does and does not do
+
+* One usage, one device. `POST /enroll` consumes a usage atomically before
+ anything is minted, so devices racing on the last usage of a code cannot
+ both win. The loser sees "Bootstrap token expired, revoked or exhausted".
+* The device keeps its identity, not the token. Its Biscuit is bound to the
+ key it generated locally and is refreshed through `/refresh`; revoking it
+ later is `sam-one admin ban <peer-id>`, exactly as for any node.
+* The token is scoped to the `sam:role:node` role. It cannot mint other
+ tokens, approve enrollments or reach the admin API; the admin token never
+ leaves the operator's terminal.
+* The code binds server and token together but the control plane does not
+ pin a token to a hostname: a token is valid at whatever URL the same
+ control plane answers on. Treat the printed line like the join token —
+ it is a credential until it is spent or expires.
diff --git a/site/content/docs/user/mobile-app.md b/site/content/docs/user/mobile-app.md
index f031f78d..9ef8ec7f 100644
--- a/site/content/docs/user/mobile-app.md
+++ b/site/content/docs/user/mobile-app.md
@@ -37,8 +37,8 @@ Exposes capabilities directly to the OS registry, allowing native assistants (li
## How to Use the Application
-1. **Enrollment**: Enter the **Control plane URL** (e.g., `https://bananas.sam-mesh.dev`) and your **Enrollment JWT**.
-2. **API Token**: Set a local API token (defaults to `secret-token`) to secure local access.
+1. **Enrollment**: Tap **Scan enrollment code** and scan the `sam://enroll` QR code printed by `sam-one` (see [Device Enrollment](../device-enrollment/)), or open **Enter details manually** to paste a bootstrap token, or sign in through the control plane's identity provider (browser or device login) with its **Control plane URL** (e.g., `https://bananas.sam-mesh.dev`).
+2. **API Token**: A local API token securing local access is generated on first launch; view or regenerate it on the Config tab.
3. **Start Node**: Launches the background Go node runtime.
4. **Dashboard**: Monitor connected peers and DHT size.
5. **Services Tab**: Enable/Disable embedded sensors (Battery/Location) to expose them to the mesh.