Sharing and Shared Drives
Roles, general access, shared drives, and why "the link" is just the item's own URL.
Sharing is where the capability model meets real people. The rules are small, and the server owns all of them, so every client behaves the same.
Roles
A role is a named bundle of capabilities. Which roles you're offered depends on what you're sharing.
A file or folder has an owner (the owner of the drive it's in) and can be shared with people, groups, the whole org, or anyone with the link.
| Role | Shown as | Can |
|---|---|---|
VIEWER | Viewer | View and download |
FULL_EDITOR | Editor | Add, edit, move and trash |
Editors can't re-share. Only the owner (or a Drive Admin, inside a shared drive) decides who else gets access.
The server refuses a role the item doesn't offer (no Drive Admin on a single file), and shareRoles(itemId) returns the right list with labels and descriptions, so the UI never hard-codes wording.
"No download" isn't a role. It's an option on a grant: the Viewer role with the download bit cleared. Your UI shows it as "Viewer, can't download".
General Access
Besides the people you add by name, an item has one general access setting:
| Level | Stored as | Roles |
|---|---|---|
| Restricted | no extra grant | n/a |
| Anyone in your organization | one TENANT grant | Viewer or Editor |
| Anyone with the link | one PUBLIC grant | Viewer only |
setGeneralAccess swaps it in a single transaction, so an item can never hold two. Both can carry an expiry, and "can't download".
Anonymous Visitors
Without a session, a request is an anonymous principal: it matches only PUBLIC grants, and the tenant comes from the item itself. Visitors can open an item, list a folder, see breadcrumbs from the shared folder down, and download (unless the grant says no download). Every write needs a session.
Shared Drives
A private drive belongs to a user, who holds every capability in it. A shared drive belongs to the tenant: nobody owns it implicitly, access comes purely from grants, and it survives its members leaving. Shared-drive names are unique per tenant, ignoring case.
Who may create? Tenant admins (SUPER_ADMIN or ADMIN), plus members of any group the admin lists under the shared_drive_creators policy (setSharedDriveCreators). Group-scoped policies live in a generic policy_groups table, so future policies reuse it.
The API
Everything is GraphQL. The management surface is small and the resolvers are one-liners over the Authorizer.
| Query | Does |
|---|---|
itemAccess(itemId) | Owner, general access, named grants, access inherited from above, whether it inherits (needs SHARE) |
shareRoles(itemId) | The roles to offer, with labels |
searchDirectory(query, ...) | People and groups for the picker (2+ characters, never lists you) |
sharedWithMe | Items shared directly with you, as entry points |
canCreateSharedDrive, sharedDriveCreators | Policy |
| Mutation | Does |
|---|---|
shareItem | Add or change a grant |
revokeAccess | Remove one |
setGeneralAccess | Restricted, org, or link |
setInheritance | Restrict or resume inheriting |
createSharedDrive, setSharedDriveCreators | Shared drives |
itemAccess is built so a client doesn't have to work anything out:
inheritedlists the access that reaches the item from folders and the drive above, nearest first. Each entry hasinheritedFrom { id, name }and is read-only here, since it's changed where it was granted. It follows the same rules as the check, so above a restriction only a drive's admins appear.idis null, and the name generic, when you can't open that ancestor.isYouis on each grant and on the owner. The server computes it from who is asking, so every client can show "(you)" and leave out the role menu and remove button on your own row, as the no-self-edit rule requires anyway.
Neither is stored. Both are computed per request.
Every item also carries myCapabilities, so the UI shows only what you can do. Errors carry a stable extensions.code: UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT or BAD_REQUEST.
The server enforces every sharing rule, whatever the UI shows. You can never grant more than you hold, and only someone with SHARE can share. See the full list in changing access.
Safety Rails
Two rules exist so that access can't be accidentally lost or quietly rewritten.
- You can't change your own access. Not by sharing an item with yourself (so you can't make yourself a viewer of your own file), not by demoting or end-dating your own grant, and not by removing it. Someone else with
SHAREhas to do it. This holds for every file, folder and drive. - A shared drive always keeps a permanent admin. The last Drive Admin grant, whether it belongs to a user or a group, can't be removed, demoted or given an end date. Make someone else an admin first. Without this, a drive whose admins all left could only be recovered by a tenant admin.
Restricting an item never locks out a drive's admins: a Drive Admin keeps full access through a restriction, so restricting adds no grant and resuming leaves none behind.
Access you hold through a group is not a grant to you, so a group member can manage that group's grant, as long as the drive keeps another admin.