Fleet Device Sharing Blueprint

Control which users can see and operate which GPS devices through an ACL permission model, with hierarchical device groups that inherit configuration and enable bulk sharing, user restrictions to l…

Feature	fleet-device-sharing
Category	Access Control
Version	1.0.0
Tags	gps, tracking, permissions, groups, sharing, fleet, access-control
YAML Source	View on GitHub
JSON API	fleet-device-sharing.json

Actors

ID	Name	Type	Description
admin	Administrator	human	Has unrestricted access to all resources; can create users and assign devices
manager	Manager	human	Can create subordinate users up to their user_limit and share devices with them
fleet_user	Fleet User	human	Has access only to explicitly shared devices and groups

Fields

Name	Type	Required	Label	Description
email	email	Yes	User’s email address; used for authentication and notifications
name	text	Yes	Full display name of the user
administrator	boolean	No	Grants unrestricted access to all platform resources
readonly	boolean	No	Prevents all write operations; user can only view data
device_readonly	boolean	No	Prevents modifications to device records while allowing full tracking access
limit_commands	boolean	No	Prevents the user from sending any commands to devices
disable_reports	boolean	No	Prevents the user from generating or downloading any reports
device_limit	number	No	Maximum number of devices this user account may have directly shared; -1 means unlimited
user_limit	number	No	Maximum number of subordinate users this user may create; 0 means user cannot create others
expiration_time	datetime	No	Date after which the user account is automatically disabled
group_name	text	No	Name of the device group
parent_group_id	hidden	No	Parent group reference enabling nested group hierarchies

Rules

• rule_1: Administrator users have implicit access to all resources; no explicit permission records are required
• rule_2: Regular users only see and interact with devices, geofences, drivers, and other resources that have been explicitly shared with them
• rule_3: Sharing a group with a user grants access to all devices currently in that group and any devices added to the group in the future
• rule_4: Group attributes are inherited by child groups and their devices; device-level attributes override inherited group values
• rule_5: A manager (user_limit > 0) can create subordinate users but cannot grant more permissions than they themselves have
• rule_6: The device_limit constrains how many devices can be shared with a given user account; administrators are exempt
• rule_7: Readonly users can view all accessible data but cannot modify any records, create events, or send commands
• rule_8: device_readonly users can track and monitor devices but cannot edit device configuration
• rule_9: limit_commands users can see device positions but cannot use the command interface
• rule_10: disable_reports users can track live positions but cannot generate historical reports or exports
• rule_11: An expired user account is treated as disabled; active sessions are invalidated

Outcomes

Device_limit_exceeded (Priority: 2) — Error: SHARING_DEVICE_LIMIT_EXCEEDED

Given:

• user has reached their device_limit
• administrator (db) eq false

Result: Sharing rejected; operator must increase the user’s device_limit or remove an existing device

Permission_revoked (Priority: 8)

Given:

• admin removes an explicit sharing permission

Then:

• delete_record target: permission
• emit_event event: permission.revoked

Result: User loses access to the resource; ongoing sessions lose visibility immediately

Device_shared_with_user (Priority: 10)

Given:

• admin or manager shares a device with a user
• user has not reached their device_limit
• sharing user has access to the device themselves

Then:

• create_record target: permission — Permission record linking user to device created
• emit_event event: device.shared

Result: User can now see the device in their fleet view and receive its events and alerts

Group_shared_with_user (Priority: 10)

Given:

• admin or manager shares a device group with a user
• sharing user has access to the group

Then:

• create_record target: permission — Permission record linking user to group created
• emit_event event: group.shared

Result: User gains access to all current and future devices in the group

Errors

Code	Status	Message	Retry
SHARING_DEVICE_LIMIT_EXCEEDED	409	This user has reached the maximum number of devices they may access	No
SHARING_PERMISSION_DENIED	403	You cannot share resources you do not have access to	No
SHARING_USER_NOT_FOUND	404	The specified user does not exist	No

Events

Event	Description	Payload
device.shared	A device has been shared with a user	device_id, user_id, shared_by
group.shared	A device group has been shared with a user	group_id, user_id, shared_by
permission.revoked	A user’s access to a resource has been removed	resource_type, resource_id, user_id

Related Blueprints

Feature	Relationship	Reason
gps-device-registration	required	Devices must be registered before they can be shared
remote-device-commands	recommended	Command access is gated by the limit_commands user restriction
fleet-scheduled-reports	recommended	Report access is gated by the disable_reports user restriction

AGI Readiness

Goals

Reliable Fleet Device Sharing

Control which users can see and operate which GPS devices through an ACL permission model, with hierarchical device groups that inherit configuration and enable bulk sharing, user restrictions to l…

Success Metrics:

Metric	Target	Measurement
unauthorized_access_rate	0%	Failed authorization attempts that succeed
response_time_p95	< 500ms	95th percentile response time

Constraints:

• security (non-negotiable): Follow OWASP security recommendations

Autonomy

Level: supervised

Human Checkpoints:

• before making irreversible changes

Escalation Triggers:

• error_rate > 5
• consecutive_failures > 3

Verification

Invariants:

• error messages never expose internal system details

Tradeoffs

Prefer	Over	Reason
security	usability	access control must enforce least-privilege principle

Coordination

Protocol: orchestrated

Consumes:

Capability	From	Fallback
gps_device_registration	gps-device-registration	fail

Safety

Action	Permission	Cooldown	Max Auto
device_shared_with_user	autonomous	-	-
group_shared_with_user	autonomous	-	-
permission_revoked	human_required	-	-
device_limit_exceeded	autonomous	-	-

Extensions (framework-specific hints)

```yaml source: repo: https://github.com/traccar/traccar project: Traccar GPS Tracking Server tech_stack: Java 17, Hibernate files_traced: 10 entry_points: - src/main/java/org/traccar/model/User.java - src/main/java/org/traccar/model/Group.java - src/main/java/org/traccar/model/Permission.java - src/main/java/org/traccar/api/security/PermissionsService.java ```