@scp-dev/hub 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Envelope, RelayCore, CoreOptions, EndpointRow, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, EndpointView, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Sql, CrossAccountLink, XDelivered, XListed, XRelease } from '@scp-dev/core';
+import { Envelope, RelayCore, CoreOptions, EndpointRow, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, EndpointView, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Sql, CrossAccountLink, XDelivered, XListed, ActivityRow, XRelease } from '@scp-dev/core';
 
 type RelayAuth = Envelope["from"]["auth"];
 /** a machine name: one relay host of an account */
@@ -58,6 +58,8 @@ interface MirrorView extends MirrorScope {
     presence?: Presence;
     last_seen?: string | null;
     title?: string | null;
+    /** the handle the endpoint had before a rename: its mirror is renamed in place */
+    was?: string;
 }
 interface RemoteView extends Omit<EndpointView, "depth">, MirrorScope {
     machine: string;
@@ -95,6 +97,8 @@ interface MirrorChange {
     added: boolean;
     presence: boolean;
     status: boolean;
+    /** the handle a renamed mirror had */
+    was?: string;
 }
 interface Delivery {
     seq: number;
@@ -110,6 +114,8 @@ interface Delivery {
 declare class FederatedCore extends RelayCore {
     readonly machine: string | null;
     private aliases;
+    private account;
+    private others;
     private scope;
     private readonly defaultAuth;
     private readonly endpointCap;
@@ -122,6 +128,12 @@ declare class FederatedCore extends RelayCore {
     /** with xinbox, a delivery takes the next seq past xinbox's too, so a bridge's replay and ack cursor stay one space */
     protected insertDelivery(messageId: string, endpoint: string, expiresAt: number): number;
     setAliases(aliases: string[]): void;
+    /** the account handle another member's machines render under, `<account>/<machine>/<handle>`; this member's own stay `me/<machine>/<handle>` */
+    setOthers(account: string, machines: Iterable<string>): void;
+    /** whether `machine` is another member's: it renders under the account handle */
+    setOther(machine: string, other: boolean): void;
+    /** how this host renders `<machine>/<handle>` of its own account */
+    remoteAddress(remote: string): string;
     /** runs `fn` with unqualified handles resolving on `machine`: a direct client's own namespace on the hub */
     within<T>(machine: string | null, fn: () => T): T;
     /** the hub-side address (`<machine>/<handle>`) an address names, another account's as it is, or null when it is on this machine */
@@ -397,6 +409,49 @@ interface HubConn {
     /** whether a human client said a terminal is attached */
     tty?: boolean;
 }
+/** a bound machine, or a revoked token's name kept as a tombstone */
+interface MachineRow {
+    name: string;
+    kind: string;
+    online: boolean;
+    bridge: boolean;
+    created_at: string | null;
+    last_seen: string | null;
+}
+/** an endpoint as the dashboard graph draws it */
+interface GraphNode {
+    address: string;
+    kind: EndpointKind;
+    harness: string | null;
+    title: string | null;
+    presence: Presence;
+    status: EndpointView["status"];
+    last_seen: string | null;
+    parent: string | null;
+    wake?: string | null;
+}
+/** `spawn`: parent to child; `message`: sender to recipient, with the count and newest send in the graph's window */
+type GraphEdge = {
+    kind: "spawn";
+    from: string;
+    to: string;
+} | {
+    kind: "message";
+    from: string;
+    to: string;
+    count: number;
+    last_at: string;
+};
+interface HubGraph {
+    /** the window message edges count over */
+    minutes: number;
+    machines: MachineRow[];
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/** the default and widest window of message edges; the core keeps an hour of sender and recipient pairs */
+declare const GRAPH_MINUTES = 15;
+declare const GRAPH_MINUTES_MAX = 60;
 interface HubSocket {
     conn: HubConn;
     send(text: string): void;
@@ -559,7 +614,10 @@ declare class RelayHub {
     private announce;
     /** a direct client's endpoint changed: the other bridges mirror it */
     private announceEndpoint;
+    /** `own` tells each bridge whether a bound machine is its member's own device */
     private toBridges;
+    /** the machines of other members than the grant's, which a bridge shows under the account handle */
+    private othersOf;
     private fleet;
     private write;
     private save;
@@ -574,8 +632,19 @@ declare class RelayHub {
     /** machines a live connection holds */
     private liveMachines;
     /** bindings, then names a revoke left behind (kind `revoked`) */
+    /** a read-only view of the account for a dashboard: its machines, listed endpoints and latest activity */
+    overview(activity?: number): {
+        machines: MachineRow[];
+        endpoints: EndpointView[];
+        activity: ActivityRow[];
+    };
+    /** a read-only graph for a dashboard: listed endpoints, spawn edges among them, and message counts per sender and recipient; never a body */
+    graph(minutes?: number): HubGraph;
     private machineList;
-    /** only the token the machine is bound to, a full login of the member who bound it, or an admin may release it (or a revoked token's name) */
+    /**
+     * only the token the machine is bound to, a full login of the member who bound it, or an admin may release it (or a revoked token's name);
+     * while no connection holds a bound machine, any credential of that member may too, so a rotated token releases what the old one bound
+     */
     private releaseMachine;
     /** releases client bindings with no live connection, idle for the `clientMachineIdleS` limit, with nothing queued and no unanswered ask open; bridge bindings never expire */
     private expireMachines;
@@ -599,4 +668,4 @@ declare class RelayHub {
     xnotice(endpoint: string, text: string): void;
 }
 
-export { type Delivery, FederatedCore, type FederatedOptions, HUB_LIMITS, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubLimits, type HubRole, type HubSocket, MACHINE_NAME, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint };
+export { type Delivery, FederatedCore, type FederatedOptions, GRAPH_MINUTES, GRAPH_MINUTES_MAX, type GraphEdge, type GraphNode, HUB_LIMITS, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubGraph, type HubLimits, type HubRole, type HubSocket, MACHINE_NAME, type MachineRow, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint };

package/dist/index.js

@@ -61,6 +61,8 @@ var handlePart = (remote) => remote.slice(remote.indexOf("/") + 1);
 var FederatedCore = class extends RelayCore {
   machine;
   aliases;
+  account = null;
+  others = /* @__PURE__ */ new Set();
   scope = null;
   defaultAuth;
   endpointCap;
@@ -102,6 +104,20 @@ var FederatedCore = class extends RelayCore {
   setAliases(aliases) {
     this.aliases = new Set(aliases);
   }
+  /** the account handle another member's machines render under, `<account>/<machine>/<handle>`; this member's own stay `me/<machine>/<handle>` */
+  setOthers(account, machines) {
+    this.account = account;
+    this.others = new Set(machines);
+  }
+  /** whether `machine` is another member's: it renders under the account handle */
+  setOther(machine, other) {
+    if (other) this.others.add(machine);
+    else this.others.delete(machine);
+  }
+  /** how this host renders `<machine>/<handle>` of its own account */
+  remoteAddress(remote) {
+    return `${this.account && this.others.has(machinePart(remote)) ? this.account : this.user}/${remote}`;
+  }
   /** runs `fn` with unqualified handles resolving on `machine`: a direct client's own namespace on the hub */
   within(machine, fn) {
     const previous = this.scope;
@@ -159,7 +175,7 @@ var FederatedCore = class extends RelayCore {
     return { account, machine, handle: handle === "me" ? "" : handle };
   }
   isLocalUser(part) {
-    return part === "me" || part === this.user || this.aliases.has(part);
+    return part === "me" || part === "local" || part === this.user || this.aliases.has(part);
   }
   /** whether an endpoint of another account `part` ever reached this relay, so `<part>/me` is that account's human */
   knownAccount(part) {
@@ -198,7 +214,7 @@ var FederatedCore = class extends RelayCore {
     return row;
   }
   addressUsers() {
-    return [this.user, "me", ...this.aliases];
+    return [this.user, "me", "local", ...this.aliases];
   }
   localRow(row) {
     return !row.remote;
@@ -206,7 +222,7 @@ var FederatedCore = class extends RelayCore {
   address(row) {
     const remote = row.remote;
     if (remote && isForeign(remote)) return remote.slice(1);
-    return remote ? `${this.user}/${remote}` : super.address(row);
+    return remote ? this.remoteAddress(remote) : super.address(row);
   }
   subject(row) {
     const remote = row.remote;
@@ -342,10 +358,17 @@ var FederatedCore = class extends RelayCore {
       const changes = [];
       const seen = options.seen ?? /* @__PURE__ */ new Set();
       const batch = [];
+      const renamed = /* @__PURE__ */ new Map();
       for (const view of parsed) {
         const remote = `${machine}/${view.handle}`;
         seen.add(remote);
-        const before = this.byRemote(remote);
+        let before = this.byRemote(remote);
+        const old = !before && view.was !== null ? this.byRemote(`${machine}/${view.was}`) : void 0;
+        if (old && old.token_hash === null) {
+          this.sql.all(`UPDATE endpoints SET remote = ? WHERE id = ?`, remote, old.id);
+          before = this.byId(old.id);
+          renamed.set(old.id, view.was);
+        }
         if (before && before.token_hash !== null) continue;
         if (!before) this.checkCap();
         batch.push({ view, id: before?.id ?? this.insertRemote(remote, view.kind, view.harness, auth, now), before });
@@ -370,14 +393,17 @@ var FederatedCore = class extends RelayCore {
           ...view.kind === "agent" ? this.scopeColumns(machine, view.scope, row, place(view.handle)) : {}
         };
         const columns = Object.entries(next).filter(([column, value]) => row[column] !== value);
-        if (!columns.length) continue;
-        this.sql.all(
-          `UPDATE endpoints SET ${columns.map(([column]) => `${column} = ?`).join(", ")} WHERE id = ?`,
-          ...columns.map(([, value]) => value),
-          id
-        );
+        const was = renamed.get(id);
+        if (!columns.length && was === void 0) continue;
+        if (columns.length)
+          this.sql.all(
+            `UPDATE endpoints SET ${columns.map(([column]) => `${column} = ?`).join(", ")} WHERE id = ?`,
+            ...columns.map(([, value]) => value),
+            id
+          );
         const change = this.diff(before, this.byId(id));
-        if (change) changes.push(change);
+        if (was !== void 0) changes.push({ ...change ?? { view: this.remoteView(this.byId(id)), added: false, presence: true, status: false }, was });
+        else if (change) changes.push(change);
       }
       if (options.full) {
         const missing = this.sql.all(
@@ -1229,7 +1255,8 @@ var FederatedCore = class extends RelayCore {
       status,
       presence,
       lastSeen: Number.isFinite(parsedSeen) ? parsedSeen : null,
-      scope: kind === "agent" ? parseScope(view) : {}
+      scope: kind === "agent" ? parseScope(view) : {},
+      was: kind === "agent" && typeof view.was === "string" && validHandle(view.was) && view.was !== handle ? view.was : null
     };
     const leaked = [handle, out.model, out.cwd, out.labels, status?.note, out.scope.title].map((v) => v ? findSecret(v) : null).find(Boolean);
     if (leaked) throw new RelayError("secret_refused", `an endpoint looks like it carries a credential (${leaked})`);
@@ -1501,6 +1528,8 @@ import {
   XLIMITS,
   xlimits
 } from "@scp-dev/core";
+var GRAPH_MINUTES = 15;
+var GRAPH_MINUTES_MAX = 60;
 var HUB_LIMITS = {
   machines: 16,
   endpoints: 512,
@@ -1969,8 +1998,8 @@ var RelayHub = class _RelayHub {
     serverFields(params);
     const observe = params.observe === true;
     const named = params.machine;
-    if ((!observe || named !== void 0) && (typeof named !== "string" || !MACHINE_NAME.test(named) || named === "me" || named === this.account)) {
-      throw new RelayError2("invalid_params", "machine is a name of lowercase letters, digits and -, other than me and the account handle");
+    if ((!observe || named !== void 0) && (typeof named !== "string" || !MACHINE_NAME.test(named) || named === "me" || named === "local" || named === this.account)) {
+      throw new RelayError2("invalid_params", "machine is a name of lowercase letters, digits and -, other than me, local and the account handle");
     }
     const bridge = params.bridge === true;
     const human = params.human === true;
@@ -2015,7 +2044,7 @@ var RelayHub = class _RelayHub {
         this.release(other, true);
       }
       core.record("bridge", null, machine, { machine });
-      return { ...base, endpoints: core.remoteViews({ except: machine }) };
+      return { ...base, endpoints: core.remoteViews({ except: machine }), others: this.othersOf(conn.grant, machine) };
     }
     if (one2(this.deps.sql, `SELECT kind FROM machines WHERE name = ?`, machine)?.kind === "bridge") {
       throw new RelayError2(
@@ -2585,7 +2614,7 @@ var RelayHub = class _RelayHub {
   /** a machine's endpoint changes: `endpoints` to the other bridges, presence and status to watchers */
   announce(machine, changes, full) {
     if (full || changes.length) {
-      const endpoints = full ? this.relay.remoteRowsOf(machine) : changes.map((c) => c.view);
+      const endpoints = full ? this.relay.remoteRowsOf(machine) : changes.map((c) => c.was === void 0 ? c.view : { ...c.view, was: c.was });
       this.toBridges(machine, { machine, endpoints, full });
     }
     for (const change of changes) {
@@ -2602,11 +2631,19 @@ var RelayHub = class _RelayHub {
     const view = this.relay.remoteRowsOf(machine).find((v) => v.id === endpoint);
     if (view) this.toBridges(machine, { machine, endpoints: [view], full: false });
   }
+  /** `own` tells each bridge whether a bound machine is its member's own device */
   toBridges(machine, params) {
+    const bound = one2(this.deps.sql, `SELECT actor_id FROM machines WHERE name = ?`, machine);
     for (const socket of this.deps.sockets()) {
-      if (socket.conn.role === "bridge" && socket.conn.machine !== machine) this.write(socket, { jsonrpc: "2.0", method: "endpoints", params });
+      if (socket.conn.role !== "bridge" || socket.conn.machine === machine) continue;
+      const own = bound ? { own: (bound.actor_id ?? null) === (socket.conn.grant.actorId ?? null) } : {};
+      this.write(socket, { jsonrpc: "2.0", method: "endpoints", params: { ...params, ...own } });
     }
   }
+  /** the machines of other members than the grant's, which a bridge shows under the account handle */
+  othersOf(grant, except) {
+    return this.deps.sql.all(`SELECT name FROM machines WHERE name != ? AND actor_id IS NOT ?`, except, grant.actorId ?? null).map((row) => row.name);
+  }
   fleet(event) {
     const at = new Date(this.now()).toISOString();
     for (const socket of this.deps.sockets()) if (socket.conn.watching) this.write(socket, { jsonrpc: "2.0", method: "fleet", params: { at, ...event } });
@@ -2721,6 +2758,43 @@ var RelayHub = class _RelayHub {
     return live;
   }
   /** bindings, then names a revoke left behind (kind `revoked`) */
+  /** a read-only view of the account for a dashboard: its machines, listed endpoints and latest activity */
+  overview(activity = 20) {
+    const { endpoints, activity: rows } = this.relay.snapshot({ activity });
+    return { machines: this.machineList(), endpoints, activity: rows };
+  }
+  /** a read-only graph for a dashboard: listed endpoints, spawn edges among them, and message counts per sender and recipient; never a body */
+  graph(minutes = GRAPH_MINUTES) {
+    const window = Math.min(Math.max(1, Math.floor(Number.isFinite(minutes) ? minutes : GRAPH_MINUTES)), GRAPH_MINUTES_MAX);
+    const endpoints = this.relay.list();
+    const byId = new Map(endpoints.map((e) => [e.id, e.address]));
+    const listed = new Set(byId.values());
+    const nodes = endpoints.map((e) => ({
+      address: e.address,
+      kind: e.kind,
+      harness: e.harness,
+      title: e.title,
+      presence: e.presence,
+      status: e.status,
+      last_seen: e.last_seen,
+      parent: e.parent ?? null,
+      ...e.wake !== void 0 ? { wake: e.wake } : {}
+    }));
+    const edges = nodes.flatMap(
+      (n) => n.parent && n.parent !== n.address && listed.has(n.parent) ? [{ kind: "spawn", from: n.parent, to: n.address }] : []
+    );
+    const pairs = this.deps.sql.all(
+      `SELECT from_ep, to_ep, COUNT(*) AS n, MAX(at) AS last FROM pair_events WHERE at > ? GROUP BY from_ep, to_ep`,
+      this.now() - window * 6e4
+    );
+    const traffic = pairs.flatMap((row) => {
+      const from = byId.get(row.from_ep);
+      const to = byId.get(row.to_ep);
+      return from && to && from !== to ? [{ kind: "message", from, to, count: row.n, last_at: iso(row.last) }] : [];
+    });
+    edges.push(...traffic.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to)));
+    return { minutes: window, machines: this.machineList(), nodes, edges };
+  }
   machineList() {
     const sockets = this.deps.sockets().filter((s) => !this.gone.has(s.conn.id));
     const bound = this.deps.sql.all(`SELECT name, kind, created_at, last_seen FROM machines ORDER BY name`).map((row) => ({
@@ -2734,7 +2808,10 @@ var RelayHub = class _RelayHub {
     const revoked = this.deps.sql.all(`SELECT name, at FROM machine_tombstones WHERE name NOT IN (SELECT name FROM machines) ORDER BY name`).map((row) => ({ name: row.name, kind: "revoked", online: false, bridge: false, created_at: null, last_seen: iso(row.at) }));
     return [...bound, ...revoked];
   }
-  /** only the token the machine is bound to, a full login of the member who bound it, or an admin may release it (or a revoked token's name) */
+  /**
+   * only the token the machine is bound to, a full login of the member who bound it, or an admin may release it (or a revoked token's name);
+   * while no connection holds a bound machine, any credential of that member may too, so a rotated token releases what the old one bound
+   */
   releaseMachine(caller, name) {
     const core = this.relay;
     if (typeof name !== "string" || !MACHINE_NAME.test(name)) throw new RelayError2("invalid_params", "name is a machine name");
@@ -2742,11 +2819,12 @@ var RelayHub = class _RelayHub {
     const tomb = bound ? void 0 : one2(this.deps.sql, `SELECT actor_id FROM machine_tombstones WHERE name = ?`, name);
     if (!bound && !tomb) throw new RelayError2("not_found", `no machine ${name}`);
     const grant = caller.conn.grant;
-    if (!(bound?.token_id === grant.tokenId || fullOf(grant, (bound ?? tomb).actor_id) || accountAdmin(grant))) {
+    const member = !!bound && bound.actor_id !== null && grant.actorId === bound.actor_id;
+    if (!(bound?.token_id === grant.tokenId || fullOf(grant, (bound ?? tomb).actor_id) || accountAdmin(grant) || member && !this.liveMachines().has(name))) {
       core.record("refuse", null, name, { code: "unauthorized", machine: name });
       throw new RelayError2(
         "unauthorized",
-        `only the token machine ${name} is bound to, a full login of the member who bound it, or an org owner or admin can release it`
+        `only the token machine ${name} is bound to, a full login of the member who bound it, or an org owner or admin can release it${member ? "; any credential of that member can once it is offline" : ""}`
       );
     }
     for (const socket of [...this.deps.sockets()]) {
@@ -2867,6 +2945,8 @@ var RelayHub = class _RelayHub {
 };
 export {
   FederatedCore,
+  GRAPH_MINUTES,
+  GRAPH_MINUTES_MAX,
   HUB_LIMITS,
   MACHINE_NAME,
   RelayHub

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/hub",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Swarm Communication Protocol federation and account hub: mirrored endpoints across machines, bridges, direct clients and cross-account delivery.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",
@@ -29,7 +29,7 @@
     "typecheck": "tsc -p ."
   },
   "dependencies": {
-    "@scp-dev/core": "0.1.0"
+    "@scp-dev/core": "0.1.2"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/federation.ts

@@ -121,6 +121,8 @@ export interface MirrorView extends MirrorScope {
   presence?: Presence
   last_seen?: string | null
   title?: string | null
+  /** the handle the endpoint had before a rename: its mirror is renamed in place */
+  was?: string
 }
 
 export interface RemoteView extends Omit<EndpointView, "depth">, MirrorScope {
@@ -154,6 +156,7 @@ type ParsedView = {
   presence: Presence
   lastSeen: number | null
   scope: ParsedScope
+  was: string | null
 }
 
 const UNKNOWN: Placement = { tree: null, parent_ep: null, depth: null }
@@ -213,6 +216,8 @@ export interface MirrorChange {
   added: boolean
   presence: boolean
   status: boolean
+  /** the handle a renamed mirror had */
+  was?: string
 }
 
 export interface Delivery {
@@ -250,6 +255,8 @@ const handlePart = (remote: string): string => remote.slice(remote.indexOf("/")
 export class FederatedCore extends RelayCore {
   readonly machine: string | null
   private aliases: Set<string>
+  private account: string | null = null
+  private others = new Set<string>()
   private scope: string | null = null
   private readonly defaultAuth: RelayAuth
   private readonly endpointCap: number | null
@@ -296,6 +303,23 @@ export class FederatedCore extends RelayCore {
     this.aliases = new Set(aliases)
   }
 
+  /** the account handle another member's machines render under, `<account>/<machine>/<handle>`; this member's own stay `me/<machine>/<handle>` */
+  setOthers(account: string, machines: Iterable<string>): void {
+    this.account = account
+    this.others = new Set(machines)
+  }
+
+  /** whether `machine` is another member's: it renders under the account handle */
+  setOther(machine: string, other: boolean): void {
+    if (other) this.others.add(machine)
+    else this.others.delete(machine)
+  }
+
+  /** how this host renders `<machine>/<handle>` of its own account */
+  remoteAddress(remote: string): string {
+    return `${this.account && this.others.has(machinePart(remote)) ? this.account : this.user}/${remote}`
+  }
+
   /** runs `fn` with unqualified handles resolving on `machine`: a direct client's own namespace on the hub */
   within<T>(machine: string | null, fn: () => T): T {
     const previous = this.scope
@@ -361,7 +385,7 @@ export class FederatedCore extends RelayCore {
   }
 
   private isLocalUser(part: string): boolean {
-    return part === "me" || part === this.user || this.aliases.has(part)
+    return part === "me" || part === "local" || part === this.user || this.aliases.has(part)
   }
 
   /** whether an endpoint of another account `part` ever reached this relay, so `<part>/me` is that account's human */
@@ -408,7 +432,7 @@ export class FederatedCore extends RelayCore {
   }
 
   protected override addressUsers(): string[] {
-    return [this.user, "me", ...this.aliases]
+    return [this.user, "me", "local", ...this.aliases]
   }
 
   protected override localRow(row: EndpointRow): boolean {
@@ -418,7 +442,7 @@ export class FederatedCore extends RelayCore {
   protected override address(row: EndpointRow): string {
     const remote = (row as FederatedRow).remote
     if (remote && isForeign(remote)) return remote.slice(1)
-    return remote ? `${this.user}/${remote}` : super.address(row)
+    return remote ? this.remoteAddress(remote) : super.address(row)
   }
 
   protected override subject(row: EndpointRow): PolicySubject {
@@ -564,10 +588,17 @@ export class FederatedCore extends RelayCore {
       const changes: MirrorChange[] = []
       const seen = options.seen ?? new Set<string>()
       const batch: { view: ParsedView; id: string; before: FederatedRow | undefined }[] = []
+      const renamed = new Map<string, string>()
       for (const view of parsed) {
         const remote = `${machine}/${view.handle}`
         seen.add(remote)
-        const before = this.byRemote(remote)
+        let before = this.byRemote(remote)
+        const old = !before && view.was !== null ? this.byRemote(`${machine}/${view.was}`) : undefined
+        if (old && old.token_hash === null) {
+          this.sql.all(`UPDATE endpoints SET remote = ? WHERE id = ?`, remote, old.id)
+          before = this.byId(old.id) as FederatedRow
+          renamed.set(old.id, view.was!)
+        }
         if (before && before.token_hash !== null) continue
         if (!before) this.checkCap()
         batch.push({ view, id: before?.id ?? this.insertRemote(remote, view.kind, view.harness, auth, now), before })
@@ -592,14 +623,17 @@ export class FederatedCore extends RelayCore {
           ...(view.kind === "agent" ? this.scopeColumns(machine, view.scope, row, place(view.handle)) : {}),
         }
         const columns = Object.entries(next).filter(([column, value]) => row[column as keyof FederatedRow] !== value)
-        if (!columns.length) continue
-        this.sql.all(
-          `UPDATE endpoints SET ${columns.map(([column]) => `${column} = ?`).join(", ")} WHERE id = ?`,
-          ...columns.map(([, value]) => value as SqlValue),
-          id,
-        )
+        const was = renamed.get(id)
+        if (!columns.length && was === undefined) continue
+        if (columns.length)
+          this.sql.all(
+            `UPDATE endpoints SET ${columns.map(([column]) => `${column} = ?`).join(", ")} WHERE id = ?`,
+            ...columns.map(([, value]) => value as SqlValue),
+            id,
+          )
         const change = this.diff(before, this.byId(id)!)
-        if (change) changes.push(change)
+        if (was !== undefined) changes.push({ ...(change ?? { view: this.remoteView(this.byId(id)!), added: false, presence: true, status: false }), was })
+        else if (change) changes.push(change)
       }
       if (options.full) {
         const missing = this.sql.all<FederatedRow>(
@@ -1546,6 +1580,7 @@ export class FederatedCore extends RelayCore {
       presence,
       lastSeen: Number.isFinite(parsedSeen) ? parsedSeen : null,
       scope: kind === "agent" ? parseScope(view) : {},
+      was: kind === "agent" && typeof view.was === "string" && validHandle(view.was) && view.was !== handle ? view.was : null,
     }
     const leaked = [handle, out.model, out.cwd, out.labels, status?.note, out.scope.title].map((v) => (v ? findSecret(v) : null)).find(Boolean)
     if (leaked) throw new RelayError("secret_refused", `an endpoint looks like it carries a credential (${leaked})`)

package/src/hub.ts

@@ -1,4 +1,5 @@
 import {
+  type ActivityRow,
   allowlisted,
   CAPABILITIES,
   CLI_NAME,
@@ -81,6 +82,44 @@ export interface HubConn {
   tty?: boolean
 }
 
+/** a bound machine, or a revoked token's name kept as a tombstone */
+export interface MachineRow {
+  name: string
+  kind: string
+  online: boolean
+  bridge: boolean
+  created_at: string | null
+  last_seen: string | null
+}
+
+/** an endpoint as the dashboard graph draws it */
+export interface GraphNode {
+  address: string
+  kind: EndpointKind
+  harness: string | null
+  title: string | null
+  presence: Presence
+  status: EndpointView["status"]
+  last_seen: string | null
+  parent: string | null
+  wake?: string | null
+}
+
+/** `spawn`: parent to child; `message`: sender to recipient, with the count and newest send in the graph's window */
+export type GraphEdge = { kind: "spawn"; from: string; to: string } | { kind: "message"; from: string; to: string; count: number; last_at: string }
+
+export interface HubGraph {
+  /** the window message edges count over */
+  minutes: number
+  machines: MachineRow[]
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+}
+
+/** the default and widest window of message edges; the core keeps an hour of sender and recipient pairs */
+export const GRAPH_MINUTES = 15
+export const GRAPH_MINUTES_MAX = 60
+
 export interface HubSocket {
   conn: HubConn
   send(text: string): void
@@ -630,8 +669,11 @@ export class RelayHub {
     serverFields(params)
     const observe = params.observe === true
     const named = params.machine
-    if ((!observe || named !== undefined) && (typeof named !== "string" || !MACHINE_NAME.test(named) || named === "me" || named === this.account)) {
-      throw new RelayError("invalid_params", "machine is a name of lowercase letters, digits and -, other than me and the account handle")
+    if (
+      (!observe || named !== undefined) &&
+      (typeof named !== "string" || !MACHINE_NAME.test(named) || named === "me" || named === "local" || named === this.account)
+    ) {
+      throw new RelayError("invalid_params", "machine is a name of lowercase letters, digits and -, other than me, local and the account handle")
     }
     const bridge = params.bridge === true
     const human = params.human === true
@@ -679,7 +721,7 @@ export class RelayHub {
         this.release(other, true)
       }
       core.record("bridge", null, machine, { machine })
-      return { ...base, endpoints: core.remoteViews({ except: machine }) }
+      return { ...base, endpoints: core.remoteViews({ except: machine }), others: this.othersOf(conn.grant, machine) }
     }
 
     if (one<{ kind: string }>(this.deps.sql, `SELECT kind FROM machines WHERE name = ?`, machine)?.kind === "bridge") {
@@ -1290,7 +1332,7 @@ export class RelayHub {
   /** a machine's endpoint changes: `endpoints` to the other bridges, presence and status to watchers */
   private announce(machine: string, changes: MirrorChange[], full: boolean): void {
     if (full || changes.length) {
-      const endpoints = full ? this.relay.remoteRowsOf(machine) : changes.map((c) => c.view)
+      const endpoints = full ? this.relay.remoteRowsOf(machine) : changes.map((c) => (c.was === undefined ? c.view : { ...c.view, was: c.was }))
       this.toBridges(machine, { machine, endpoints, full })
     }
     for (const change of changes) {
@@ -1309,12 +1351,23 @@ export class RelayHub {
     if (view) this.toBridges(machine, { machine, endpoints: [view], full: false })
   }
 
-  private toBridges(machine: string, params: unknown): void {
+  /** `own` tells each bridge whether a bound machine is its member's own device */
+  private toBridges(machine: string, params: Record<string, unknown>): void {
+    const bound = one<{ actor_id: string | null }>(this.deps.sql, `SELECT actor_id FROM machines WHERE name = ?`, machine)
     for (const socket of this.deps.sockets()) {
-      if (socket.conn.role === "bridge" && socket.conn.machine !== machine) this.write(socket, { jsonrpc: "2.0", method: "endpoints", params })
+      if (socket.conn.role !== "bridge" || socket.conn.machine === machine) continue
+      const own = bound ? { own: (bound.actor_id ?? null) === (socket.conn.grant.actorId ?? null) } : {}
+      this.write(socket, { jsonrpc: "2.0", method: "endpoints", params: { ...params, ...own } })
     }
   }
 
+  /** the machines of other members than the grant's, which a bridge shows under the account handle */
+  private othersOf(grant: HubGrant, except: string): string[] {
+    return this.deps.sql
+      .all<{ name: string }>(`SELECT name FROM machines WHERE name != ? AND actor_id IS NOT ?`, except, grant.actorId ?? null)
+      .map((row) => row.name)
+  }
+
   private fleet(event: Record<string, unknown>): void {
     const at = new Date(this.now()).toISOString()
     for (const socket of this.deps.sockets()) if (socket.conn.watching) this.write(socket, { jsonrpc: "2.0", method: "fleet", params: { at, ...event } })
@@ -1442,7 +1495,46 @@ export class RelayHub {
   }
 
   /** bindings, then names a revoke left behind (kind `revoked`) */
-  private machineList(): { name: string; kind: string; online: boolean; bridge: boolean; created_at: string | null; last_seen: string | null }[] {
+  /** a read-only view of the account for a dashboard: its machines, listed endpoints and latest activity */
+  overview(activity = 20): { machines: MachineRow[]; endpoints: EndpointView[]; activity: ActivityRow[] } {
+    const { endpoints, activity: rows } = this.relay.snapshot({ activity })
+    return { machines: this.machineList(), endpoints, activity: rows }
+  }
+
+  /** a read-only graph for a dashboard: listed endpoints, spawn edges among them, and message counts per sender and recipient; never a body */
+  graph(minutes = GRAPH_MINUTES): HubGraph {
+    const window = Math.min(Math.max(1, Math.floor(Number.isFinite(minutes) ? minutes : GRAPH_MINUTES)), GRAPH_MINUTES_MAX)
+    const endpoints = this.relay.list() as (EndpointView & { wake?: string | null })[]
+    const byId = new Map(endpoints.map((e) => [e.id, e.address]))
+    const listed = new Set(byId.values())
+    const nodes: GraphNode[] = endpoints.map((e) => ({
+      address: e.address,
+      kind: e.kind,
+      harness: e.harness,
+      title: e.title,
+      presence: e.presence,
+      status: e.status,
+      last_seen: e.last_seen,
+      parent: e.parent ?? null,
+      ...(e.wake !== undefined ? { wake: e.wake } : {}),
+    }))
+    const edges: GraphEdge[] = nodes.flatMap((n) =>
+      n.parent && n.parent !== n.address && listed.has(n.parent) ? [{ kind: "spawn" as const, from: n.parent, to: n.address }] : [],
+    )
+    const pairs = this.deps.sql.all<{ from_ep: string; to_ep: string; n: number; last: number }>(
+      `SELECT from_ep, to_ep, COUNT(*) AS n, MAX(at) AS last FROM pair_events WHERE at > ? GROUP BY from_ep, to_ep`,
+      this.now() - window * 60_000,
+    )
+    const traffic: GraphEdge[] = pairs.flatMap((row) => {
+      const from = byId.get(row.from_ep)
+      const to = byId.get(row.to_ep)
+      return from && to && from !== to ? [{ kind: "message" as const, from, to, count: row.n, last_at: iso(row.last)! }] : []
+    })
+    edges.push(...traffic.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to)))
+    return { minutes: window, machines: this.machineList(), nodes, edges }
+  }
+
+  private machineList(): MachineRow[] {
     const sockets = this.deps.sockets().filter((s) => !this.gone.has(s.conn.id))
     const bound = this.deps.sql
       .all<{ name: string; kind: string; created_at: number; last_seen: number | null }>(`SELECT name, kind, created_at, last_seen FROM machines ORDER BY name`)
@@ -1460,7 +1552,10 @@ export class RelayHub {
     return [...bound, ...revoked]
   }
 
-  /** only the token the machine is bound to, a full login of the member who bound it, or an admin may release it (or a revoked token's name) */
+  /**
+   * only the token the machine is bound to, a full login of the member who bound it, or an admin may release it (or a revoked token's name);
+   * while no connection holds a bound machine, any credential of that member may too, so a rotated token releases what the old one bound
+   */
   private releaseMachine(caller: HubSocket, name: unknown): unknown {
     const core = this.relay
     if (typeof name !== "string" || !MACHINE_NAME.test(name)) throw new RelayError("invalid_params", "name is a machine name")
@@ -1468,11 +1563,12 @@ export class RelayHub {
     const tomb = bound ? undefined : one<{ actor_id: string | null }>(this.deps.sql, `SELECT actor_id FROM machine_tombstones WHERE name = ?`, name)
     if (!bound && !tomb) throw new RelayError("not_found", `no machine ${name}`)
     const grant = caller.conn.grant
-    if (!(bound?.token_id === grant.tokenId || fullOf(grant, (bound ?? tomb)!.actor_id) || accountAdmin(grant))) {
+    const member = !!bound && bound.actor_id !== null && grant.actorId === bound.actor_id
+    if (!(bound?.token_id === grant.tokenId || fullOf(grant, (bound ?? tomb)!.actor_id) || accountAdmin(grant) || (member && !this.liveMachines().has(name)))) {
       core.record("refuse", null, name, { code: "unauthorized", machine: name })
       throw new RelayError(
         "unauthorized",
-        `only the token machine ${name} is bound to, a full login of the member who bound it, or an org owner or admin can release it`,
+        `only the token machine ${name} is bound to, a full login of the member who bound it, or an org owner or admin can release it${member ? "; any credential of that member can once it is offline" : ""}`,
       )
     }
     for (const socket of [...this.deps.sockets()]) {

package/src/index.ts

@@ -12,4 +12,20 @@ export {
   type RemoteView,
   type XEndpoint,
 } from "./federation"
-export { HUB_LIMITS, RelayHub, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubLimits, type HubRole, type HubSocket } from "./hub"
+export {
+  GRAPH_MINUTES,
+  GRAPH_MINUTES_MAX,
+  type GraphEdge,
+  type GraphNode,
+  type HubGraph,
+  HUB_LIMITS,
+  RelayHub,
+  type HubAuth,
+  type HubConn,
+  type HubDeps,
+  type HubGrant,
+  type HubLimits,
+  type HubRole,
+  type HubSocket,
+  type MachineRow,
+} from "./hub"