Edge / User Admin

Appearance

Disconnect ​

Disconnecting (revoking the Host Link) ends this Device's bond with the paired HiveCast account. After disconnect:

  • The Device's NATS user JWT is rejected (account-level revocation).
  • Heartbeats fail.
  • The cloud routes (hivecast.ai/<spacePath>/edge/) no longer reach this Device.
  • The Host Link record on the platform is marked revoked (kept for audit).

Local use continues unaffected. Apps on 127.0.0.1 keep working.

When to disconnect ​

  • Decommissioning — selling, recycling, or repurposing the Device.
  • Lost or stolen — disconnect immediately so the leaked credentials become useless.
  • Switching accounts — disconnect from one HiveCast account before pairing to another.
  • Periodic cleanup — old test pair you no longer need.

How to disconnect ​

From the HiveCast Devices page (preferred) ​

Status: implemented. Per richard-ui-revoke-proof-20260501-064035.

  1. Open https://hivecast.ai/apps/web/#dashboard.
  2. Find this Device in the Linked Devices list.
  3. Click the revoke action.
  4. Confirm.

From CLI on this Device ​

bash
hivecast logout --revoke-cloud-link --home <host-home>
# or
hivecast logout --all --home <host-home>

--local-only keeps the Host Link on the platform but clears local credentials (rare; usually you want full revoke).

--revoke-cloud-link revokes the platform Host Link and clears local credentials.

--all does everything — revoke + local clear + future-pair-friendly cleanup.

From CLI on any signed-in Device ​

bash
matrix invoke system.auth auth.hostLink.revoke \
  '{"hostLinkId":"<id>"}' --home <host-home>

You can do this from a different Device (e.g., your phone) if the Device you're disconnecting is unreachable.

What revoke does ​

Per HiveCast Platform / Devices / Disconnect / unlink:

  1. Sets link.status = 'revoked', link.revokedAt = <now>.
  2. Updates the principal NATS account JWT to add this Device's user public keys to the revocation list.
  3. NATS hub reloads.
  4. The Device's existing NATS user JWT is now rejected by the hub.
  5. system.devices shows the Device as revoked.

What revoke does NOT do ​

  • Does not delete <host-home>/.
  • Does not stop the local Host.
  • Does not delete local apps or data.
  • Does not break local-owner mode.
  • Does not affect other Devices.

Verifying the disconnect ​

bash
# Local credential file should be gone
ls <host-home>/credentials/hivecast-link.json
# (after hivecast logout --all)

# On any other paired Device:
matrix invoke system.devices devices.list \
  '{"principalId":"<your-id>","includeRevoked":true}'
# Look for the Device with status: 'revoked'.

# Try the cloud URL:
curl -i https://hivecast.ai/<spacePath>/edge/
# Should return an error or fall back to other paired Devices' Edge routes.

Re-pairing ​

A revoked Device can re-pair by running hivecast login --device --cloud https://hivecast.ai again. A new Host Link record is created (the old revoked one stays for audit). The Device gets fresh credentials.

Authorization ​

Per the spec:

  • The HTTP path POST /api/devices/:deviceId/revoke requires a session for the link's owner principal.
  • The CLI op accepts the call from anyone with the correct credentials (loopback for local-client, principal session for remote).
  • A different principal cannot revoke your Device.

Lost Device scenario ​

If the Device is lost or stolen:

  1. From any other paired Device or a browser at hivecast.ai, revoke the lost Device's Host Link.
  2. Refresh credentials on remaining Devices to be safe:
    bash
    matrix invoke system.auth auth.hostLink.credentials.refresh \
  '{"principalId":"<your-id>","hostLinkId":"<id>"}' --home <host-home>
  3. Audit recent activity on your Space for the period the Device was missing.

See also ​

Source: projects/matrix-3/packages/system-auth/src/index.ts:790-803 for the op. Live revoke proofs in WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md Step 7.