Bind a worker's name and labels into its token; list and revoke tokens by jti

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013GAeg4Jo6xjZzjwy9QDWMQ

docs/code/api.md

@@ -229,7 +229,9 @@ the process is dead.
 | Method | Path | What |
 |---|---|---|
 | `GET` | `/workers` | what is attached, its labels and how busy it is |
-| `POST` | `/workers/tokens` | mint a worker credential (superuser; shown once) |
+| `POST` | `/workers/tokens` | mint a worker credential with its name and labels (superuser; shown once) |
+| `GET` | `/workers/tokens` | the worker credentials minted, without the tokens (superuser) |
+| `POST` | `/workers/tokens/{jti}/revoke` | refuse one from now on and drop a worker attached with it (superuser) |
 | `GET` | `/workers/runtime` | the node runner's source, for a host without pip |
 | `WS` | `/workers/attach` | where a worker dials in |
 

docs/code/workers.md

@@ -30,8 +30,8 @@ driver in order to run a training step. An engine host already has it, and
 |---|---|---|
 | `--url` | **required** | `wss://…/api/v1/workers/attach` |
 | `--token` | `$FLUKSIO_WORKER_TOKEN` | the credential, minted on the engine |
-| `--name` | this host's name | how it shows up in the worker list |
-| `--labels` | none | comma-separated; what a node's `device` matches |
+| `--name` | this host's name | sent along; the worker list shows the token's name |
+| `--labels` | the token's | comma-separated; must match the labels the token was minted with |
 | `--python` | this interpreter | the interpreter node code runs on |
 | `--parallel` | `1` | how many node calls it will take at once |
 | `--artifact-url` | derived from `--url` | where the artifact store is, if not beside the socket |
@@ -84,12 +84,26 @@ On the engine, as a superuser:
 
 ```sh
 curl -X POST $FLUKSIO/workers/tokens -H "Authorization: Bearer $TOKEN" \
-  -H 'Content-Type: application/json' -d '{"name": "gpu-dev"}'
+  -H 'Content-Type: application/json' \
+  -d '{"name": "gpu-dev", "labels": ["gpu", "cuda12"]}'
 ```
 
 Shown once, valid for a year, since a worker is a machine somebody sets up and
-leaves running. It is signed with the same keypair agent tokens use, so
-rotating that key revokes every worker along with them.
+leaves running. The name and labels are signed into it: labels decide which
+nodes, with their source and secrets, are sent to a worker, so a worker cannot
+choose its own. It shows up under the token's name, and a worker whose
+`--labels` differ from the token's is refused.
+
+```sh
+curl -s $FLUKSIO/workers/tokens -H "Authorization: Bearer $TOKEN" | jq
+curl -X POST $FLUKSIO/workers/tokens/$JTI/revoke -H "Authorization: Bearer $TOKEN"
+```
+
+The first lists what was minted, by `jti` (the tokens themselves are not
+kept); the second refuses one from then on, here and at the artifact
+endpoint, and drops a worker attached with it. Rotating the keypair agent
+tokens are signed with still revokes every worker at once. A token minted
+before tokens carried their labels is refused: mint a new one.
 
 ??? note "A host where pip is not an option"
 
@@ -181,6 +195,10 @@ will never accept it; `pip install -U fluksio-worker` on that host is the whole
 upgrade. Nothing changed in the runner served at `GET /api/v1/workers/runtime`,
 so a host that copies its two files copies the same one as before.
 
+A token minted before tokens carried their labels and a `jti` is refused. Mint
+each existing worker host a new one with `POST /workers/tokens`, naming the
+labels it should carry, and swap it in for `FLUKSIO_WORKER_TOKEN`.
+
 ## Machines from a batch scheduler
 
 A cluster is not a machine that attaches and stays; it is a queue somebody else

docs/concepts/runs.md

@@ -264,7 +264,7 @@ nothing should expose Redis across hosts. Install it on the box, mint it a
 token, and start it:
 
 ```bash
-curl -X POST $FLUKSIO/workers/tokens -d '{"name": "gpu-dev"}'   # once, as an admin
+curl -X POST $FLUKSIO/workers/tokens -d '{"name": "gpu-dev", "labels": ["gpu", "cuda12"]}'   # once, as an admin
 
 pip install fluksio-worker
 

docs/getting-started/facility-automation.md

@@ -252,9 +252,12 @@ On the engine, mint a token:
 
 ```sh
 curl -X POST https://api.${DOMAIN}/api/v1/workers/tokens \
-  -H "Authorization: Bearer $TOKEN" -d '{"name": "shed-pi"}'
+  -H "Authorization: Bearer $TOKEN" -d '{"name": "shed-pi", "labels": ["shed", "gpio"]}'
 ```
 
+The labels are signed into it, so the worker can repeat them with `--labels`
+but not change them.
+
 On the other machine:
 
 ```sh