Access and delegation

Every protected file operation resolves through one authority, resolve_file_access, evaluated live on every call — never a snapshot taken when a grant was created. Folder-level authority resolves the identical way down an entire Root Folder subtree (issue #55; see Inherited access through a Root Folder subtree below). This page explains what that means in practice; Security and authorization is the authoritative permission model.

Grant levels

Access levels form a strict order: read < write < manage.

Level	Can inspect / download	Can add a content version	Can change metadata / archive / restore	Can manage grants
read	Yes	No	No	No
write	Yes	Yes	No	No
manage	Yes	Yes	Yes	Yes, within your own delegation limit

Ownership always implies manage on the owned file. A grant never authorizes less than the requester already has through another path — your effective permission is the highest level you hold from any source (ownership, a direct grant, or a group grant).

Grant or revoke access to a file

tv file access grant <file-id> --user someone@example.com --level write --reason "Reviewing draft"
tv file access grant <file-id> --group finance-team --level read
tv file access revoke <file-id> --user someone@example.com
tv file access list <file-id>

Granting, revoking, or listing a file's access requires manage on that file (which ownership always satisfies). A caller who lacks manage sees the exact same NOT_FOUND a genuinely missing file would produce — access grants are anti-enumeration surfaces too, not just files themselves.

Grant access to a whole Root Folder

tv folder access grant "Finance" --group finance-team --level write --reason "Q3 reviewers"
tv folder access list "Finance"

Granting, revoking, or listing a Root Folder's access requires live manage on that folder itself -- ownership, a direct grant, a group grant, or a grant inherited from one of its own ancestors (see below) -- re-evaluated fresh on every call. A caller without that authority sees the same anti-enumerating NOT_FOUND a nonexistent Root Folder would produce.

Inherited access through a Root Folder subtree

A Root Folder grant applies to that folder, every descendant subfolder beneath it, and every file contained anywhere in that subtree (issue #55) -- not only files the grantor happens to own. Effective access to any folder or file is always the maximum across every source that reaches it, resolved live on every call, never a snapshot taken when the grant was created:

• Ownership -- Root Folder ownership implies manage throughout the folder's entire subtree, not only the folder itself.
• A direct grant on the file or folder itself.
• A group grant, direct or via active membership.
• Every ancestor Root Folder's own grant, at any distance up the tree -- a grant made several levels up still reaches a file at the bottom; when two ancestors at different levels each grant a different level, the higher level wins.

Delegation stays strictly bounded. A grantor may never delegate a level higher than their own current effective manage authority, and only within the subtree they currently manage -- the same live check that already bounds file grants applies identically to folder grants, re-evaluated fresh on every grant attempt, never cached from when that authority was first established. If a grantor's own access to part of a subtree is later revoked, everyone who received access to it only through that grantor's own delegated grant loses it too, live, with no separate cleanup step.

Moving a subfolder to a new parent (tv folder move) immediately recalculates every inherited grant beneath it against its new ancestor chain -- no permission snapshot is ever copied at move time. Revoking a grant, removing a group member, or deactivating a subject changes effective access for every folder and file it reaches immediately, on the very next call.

A folder or file that is unreachable through this resolution -- whether by direct denial or simply by living deep inside a subtree you cannot reach -- produces the identical anti-enumerating NOT_FOUND a nonexistent one would; nothing about why access was denied is ever revealed.

A delegating user can never grant more authority than they currently hold. If you only have write on a file or folder, you cannot grant someone else manage on it.

Groups

Any active organization member can create a group and becomes its sole owner:

tv group create finance-team
tv group invite finance-team someone@example.com --role member
tv group invites
tv group accept <invite-id>
tv group members finance-team
tv group remove-member finance-team someone@example.com
tv group role finance-team someone@example.com manager
tv group transfer finance-team someone@example.com
tv group list

Groups are flat (no nesting), organization-local, and named per-owner: two different owners may each have a group called "Engineering", but the same owner cannot reuse a name across their own active or previously deactivated groups. Every group member holds exactly one role:

Role	Invite / remove members	Change roles	Transfer ownership
owner	Yes	Any role, including promoting to owner	Yes
manager	Yes	Any role except promoting to owner	No
member	No	No	No

At least one active owner must remain at all times — no role change, removal, or transfer can leave a group ownerless. tv group transfer <group> <email> is the one-step, owner-only handoff: the caller becomes manager and the target becomes owner atomically, so a group is never briefly without an owner.

Invitations

Creating a membership is never silent. tv group invite <group> <email> [--role manager|member] (default member) sends a pending invitation to an existing active Vault member; they list it with tv group invites and must explicitly tv group accept <invite-id> or tv group decline <invite-id> — nothing is added until they accept. Inviting an email that does not belong to an active member of your organization returns the identical success response a real invitation would, but creates nothing: deliberate anti-enumeration, the same principle applied everywhere else existence itself is sensitive information. Re-inviting an email with an existing pending invitation refreshes that same invitation rather than creating a duplicate; a group has at most one pending invitation per email.

Removing a member (tv group remove-member) immediately removes their group-derived file access on the next access check; any grant made to them directly (not through the group) is untouched.

A grant to a group applies to every current member; membership changes take effect immediately, since resolution is always live — never cached.

Administrator oversight

Administrators discover and, when necessary, intervene in any group without gaining implicit membership — see Users, roles, and groups for the full tv admin group list|members|remove-member|transfer surface.

What changes when you move a file or folder

Moving a file to a different Root Folder (tv file move) immediately recalculates which Root Folder-scoped grants apply to it -- direct, group, and every ancestor of its new parent -- see Working with files. Effective access can appear or disappear as a side effect; tv file move warns and requires confirmation whenever that would actually happen. Moving a subfolder (tv folder move) does the identical live recalculation for its entire subtree at once -- see Inherited access through a Root Folder subtree above.

What administrators can see without a grant

An administrator (admin/global_admin) may list, inspect, and download every folder and file in their own organization -- not just their own or granted content -- with no direct or inherited grant required (issue #55). --admin-reason <reason> may still be supplied to tv file info/tv file get and is recorded on the audit event when given, but it is never required and never blocks the request. Every such access, reasoned or not, writes its own audit event carrying an explicit adminOverride: true indicator -- unrestricted access is still explicit and accountable, never silent, and it never mutates ownership or creates an implicit access-grant row. It is also always bound to the administrator's own organization: an administrator can never see or act on another organization's content this way. See Audit and administration.

Continue with Working with files or the Command reference for exact syntax and every error code.