HiveCast Platform

Appearance

Operations: Disconnect a device ​

For user-facing disconnect, see Devices / Disconnect / unlink. This page covers the admin/operator perspective.

When an admin disconnects a Device ​

Common scenarios:

  • Lost or stolen Device. User reports it; admin revokes immediately so the Device cannot reach the bus.
  • Compromised credential. A Device's NATS user JWT may have leaked; revoke that link.
  • Account suspension. A principal is being suspended; revoke every Host Link they own.
  • Service-level cleanup. Old test Devices left over.

Direct revoke ​

bash
# By Host Link id
matrix invoke system.auth auth.hostLink.revoke \
  '{"hostLinkId":"<id>"}'

# By host id (the install identity)
matrix invoke system.auth auth.hostLink.revoke \
  '{"hostId":"<install-id>","principalId":"p_xxx"}'

The op (system-auth/src/index.ts:790-803) flips status to revoked, sets revokedAt, and triggers NATS user public-key revocation through the account JWT. The NATS hub reloads.

Verifying the revoke took effect ​

bash
matrix invoke system.auth auth.hostLink.get '{"hostLinkId":"<id>"}'
# Should show status: 'revoked', revokedAt: <ts>.

matrix invoke system.devices devices.list \
  '{"principalId":"p_xxx","includeRevoked":true}'
# Should include the row with status: 'revoked'.

# On the (former) Device, attempt a heartbeat:
# Expect 401 Unauthorized.
# Attempt a NATS connection: expect auth failure.

Bulk revoke for a principal ​

When suspending a principal, revoke every Host Link they own:

bash
matrix invoke system.auth auth.hostLink.list \
  '{"principalId":"p_xxx"}' | jq -r '.hostLinks[].id' | \
  while read id; do
    matrix invoke system.auth auth.hostLink.revoke "{\"hostLinkId\":\"$id\"}"
  done

Each revoke triggers a NATS hub reload — under fleet pressure, this is slow. A bulk-revoke op is target state.

Authorization ​

Per HIVECAST-DEVICE-ENROLLMENT-SPEC.md, Host Link revoke is authenticated and principal-bound:

  • The HTTP path POST /api/devices/:deviceId/revoke requires a session for the link's principal.
  • The CLI path requires the calling identity to match the link's principal — or be a local-client (loopback) identity.

For an admin acting on a user's behalf today, the loopback identity on the platform Host is the only path. Target state: an admin: true flag on principals plus an op-level scope.

What revoke does NOT do ​

Per Devices / Disconnect / unlink:

  • Does not delete local data on the Device.
  • Does not stop local apps on the Device.
  • Does not affect other Devices.
  • Does not unclaim namespace.

Re-pairing after admin revoke ​

A revoked Device can be re-paired by the user (creating a fresh Host Link). The old revoked record stays in storage for audit.

What to log when admin-revoking ​

Until structured audit ships, manually note:

  • Reason for revoke (lost, compromised, suspended, cleanup).
  • Time, who initiated.
  • Whether the user was notified.
  • The hostLinkId and principalId.

A target audit pipeline auto-records all of this.

See also ​

Source: projects/matrix-3/packages/system-auth/src/index.ts:790-803 for the op.