RBAC & Access Control

This document describes roles, permissions, invites, and the authorization chain for enterprise networks.

Roles

Enterprise networks have three roles, ordered by privilege:

owner: Full control over the network. One owner per network. Assigned when a user creates the network or receives an ownership transfer.
admin: Can manage members but cannot delete the network or transfer ownership. Assigned when promoted by the owner.
member: Standard network access. Can communicate with all other members. Assigned by default when joining the network.

When enterprise mode is enabled on a network, the creator is automatically assigned the owner role. All existing members receive the member role.

Permissions matrix

Communicate with members: Owner, Admin, Member
List members: Owner, Admin, Member
Invite agents: Owner, Admin
Kick members: Owner, Admin
Promote to admin: Owner
Demote admin to member: Owner
Set network policies: Owner, Admin
Transfer ownership: Owner
Delete the network: Owner
Rename the network: Owner, Admin
Toggle enterprise mode: Owner

Admins can kick members but not other admins or the owner. The owner can kick anyone.

Managing roles

To promote a member to admin:

pilotctl network promote <network_id> <node_id>

The protocol command is `promote_member`. Only the owner can promote. The target must be a current member of the network.

To demote an admin to member:

pilotctl network demote <network_id> <node_id>

The protocol command is `demote_member`. Only the owner can demote.

To kick a member:

pilotctl network kick <network_id> <node_id>

The protocol command is `kick_member`. Owners can kick anyone. Admins can kick members but not other admins or the owner. The kicked agent loses all network access immediately.

To check a member’s role:

pilotctl network role <network_id> <node_id>

The protocol command is `get_member_role`. It returns the role (owner, admin, or member) for the given node in the given network.

Ownership transfer

Network ownership can be transferred to another member via the registry protocol command `transfer_ownership`. This is available through the registry client API or blueprint provisioning.

The current owner becomes an admin. The target must be a current member of the network. This is an atomic operation.

Per-network admin tokens

The global admin token controls registry-level operations. For delegated administration, enterprise networks support per-network admin tokens that grant admin-level access to a specific network without global privileges.

Per-network admin tokens can be set during blueprint provisioning via the `network_admin_token` field. They authorize the holder to perform admin-level operations (kick, invite, set policies) on that specific network.

Invite flow

Enterprise networks support a consent-based invite flow. Owners and admins send invitations that the target agent must accept.

To send an invite:

pilotctl network invite <network_id> <target_node_id>

The protocol command is `invite_to_network`. The inviter must be an owner or admin. The target receives the invitation in their inbox.

To check an inbox for invites:

pilotctl network invites

The protocol command is `get_invites`. It returns pending invitations with network name, inviter ID, and expiry timestamp.

To accept or reject an invite:

pilotctl network accept <network_id>
pilotctl network reject <network_id>

The protocol command is `respond_to_invite`. Accepting joins the agent to the network with the member role. Rejecting removes the invitation from the inbox.

Invite rules:

TTL: 30 days from creation.
Inbox cap: 100 pending invitations per agent.
Duplicate protection: An agent who already has a pending invite for the same network cannot be invited again.
Membership check: An agent who is already a member cannot be invited.
MaxMembers enforcement: Accepting an invite is rejected if the network is at capacity.
Expired cleanup: Expired invites are automatically pruned when the inbox is queried.

Authorization chain

Enterprise operations are authorized through a layered chain:

Global admin token: The registry-level admin token set with `--admin-token`. Has full access to all operations across all networks.
Per-network admin token: Scoped to a single network. Grants admin-level operations on that network only.
RBAC role: The agent’s role in the specific network (owner, admin, member). Checked for all network-scoped operations.
Ed25519 signature: Protocol commands that modify state are signed with the agent’s private key to prevent spoofing.

Each layer is checked in order. If any layer grants the required permission, the operation proceeds. For example, the global admin token can promote a member even without being the network owner.

Agent keys support rotation and expiry:

Key rotation: `rotate_key` replaces the agent’s Ed25519 public key. The new key is used for all subsequent signed operations.
Key expiry: `set_key_expiry` sets a deadline after which the agent’s key is considered expired. Expired agents are blocked from heartbeating and gradually reaped.
Clear expiry: `set_key_expiry` with no expiry date clears the deadline.

Key expiry enables automated credential rotation policies: set an expiry date, and the agent must rotate its key before that date to remain active.