Personal state
Personal state is the data a principal records about itself while using the library: bookmarks, favorites, ratings, playback position and history, and interface preferences. It describes the viewer, not the record being viewed.
Cove authorizes personal state separately from the records it refers to. A read permission on an entity kind allows both reading those entities and writing your own personal state about them. Changing the entities themselves requires the corresponding write permission.
Three tiers
Section titled “Three tiers”Each protected operation falls into one of three tiers, and the tier decides which permission governs it.
Library state is the shared record: entity metadata, relationships, files, and generated media. Every principal sees the same values. Writing it requires the write or delete permission for that entity kind, and deleting an underlying file requires its own additional permission.
Personal state is per-user and visible only to its owner. Writing it requires the read permission for the entity kind the state refers to. Recording a bookmark on a video requires the video read permission, not the video write permission.
Account state is the principal’s own account: interface preferences, active sessions, external identity links, and password. It is governed by authentication rather than by a named permission, so any authenticated principal can act on its own account.
What a read permission allows
Section titled “What a read permission allows”A principal holding only a read permission for an entity kind can, for entities of that kind it is allowed to see:
- Add and remove bookmarks.
- Set and clear favorites.
- Set and clear ratings, including per-aspect ratings.
- Record playback intervals, resume position, play counts, and completion.
- Record behavioral interactions such as page visits and detail opens.
- Reset or wipe its own recorded activity.
This is deliberate. A role that grants only read permissions — the built-in Viewer role, for example — is still a usable account: the person can mark what they have watched, save items for later, and rate them, without being able to alter the library that everyone else sees.
Scope of a personal-state write
Section titled “Scope of a personal-state write”Personal-state writes are confined to the principal’s own rows. A principal cannot read, alter, or clear another user’s bookmarks, ratings, playback history, or preferences, and no personal-state operation changes a library record, a file on disk, or a value another user sees.
The reset and wipe operations follow the same boundary. They clear the calling user’s own recorded activity only, and they distinguish signals the user set deliberately from signals the system collected: a wipe of collected activity preserves ratings, likes, favorites, and bookmarks.
API tokens
Section titled “API tokens”An API token carries its user’s permissions, narrowed by the token’s scope. The tiers apply to it unchanged, which has one consequence worth stating directly:
A token scoped to read permissions can still write the personal state of the user that owns it. A read-scoped token can bookmark, favorite, rate, and record playback history for its owner, and can clear that owner’s recorded activity. It cannot change library records, and it cannot affect any other user.
Scoping a token to read permissions therefore protects the shared library, not the owner’s personal state. An integration that must not disturb the owner’s bookmarks, ratings, or playback history should run as a dedicated local user created for that integration, so that whatever personal state it records belongs to that account rather than to a person’s.