dashboard: a token handed over to another member's dashboard

Opening another member's dashboard passes a token reading only, for
five minutes, in the URL's fragment; its login page begins a session
with it. Tokens may be asked for with a shorter lifetime.

Auth plan M3 (hand-off).

3 files changed, 10 insertions, 3 deletions

diff --git a/docs/access.md b/docs/access.md
index 44c89f3..1ee9994 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -99,7 +99,9 @@ curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store
   a capability granted or revoked counts on a node as soon as the change reaches it.
 * **How long**: `--token-lifetime` (12 hours), refreshed (`POST /auth/refresh`, on any
   node, which signs the new one) until `--session-lifetime` (7 days) after the login;
-  then the user logs in again. A refreshed token may say less (`limit`), never more.
+  then the user logs in again. A refreshed token may say less (`limit`), never more,
+  and live less (`lifetime`, in seconds): a dashboard opening another member's hands it
+  one reading only, for five minutes ([`dashboard.md`](dashboard.md)).
 * **Revoking**: a user disabled or removed is refused at once; all of a user's tokens,
   by the user (`POST /auth/logout`) or by one who may manage users (`DELETE
   /admin/users/{name}/tokens`), which sets `_continuum/logouts/<name>`: tokens issued
diff --git a/docs/dashboard.md b/docs/dashboard.md
index 271592a..322abc6 100644
--- a/docs/dashboard.md
+++ b/docs/dashboard.md
@@ -200,8 +200,10 @@ measured.
 * **Right-click a node**: its menu: subscribing, and opening its dashboard.
 * **Open a node's dashboard** (its menu): in this page, where the node publishes one
   (`--dashboard-url`, in the member list; e.g. behind a reverse proxy,
-  [`operations.md`](operations.md)). The other dashboard asks for its own credentials
-  where its proxy or node does. It opens as this one was left: the map's nodes where
+  [`operations.md`](operations.md)). A token from this node goes along, reading only,
+  for five minutes: where the browser has no session at the other dashboard, its login
+  page begins one with it (reading only; log in there to do more), unless its proxy asks
+  for credentials of its own. It opens as this one was left: the map's nodes where
   they were (on a dynamic map they then move to their places among the other node's
   links, smoothly; new ones are placed among them), the view, the pins, what is in
   focus, the legend shown or hidden, what is open in the figures and in the document,
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 9b75618..d3715b1 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1962,6 +1962,9 @@ components:
         limit:
           type: array
           items: { $ref: '#/components/schemas/CapabilityRequest' }
+        lifetime:
+          type: integer
+          description: Seconds the token lives, if less than `token-lifetime` (a token to hand over, say).
     TokenAnswer:
       type: object
       properties: