Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Resource Access Control (ACL)
OpenViking ACL shares directories or files from the shared resource scope with users or groups inside one account. ACL never changes the account boundary: every grant is limited to the current account.
ACL uses a collaborative-document inheritance model. A directory grant applies to descendants by default. Child directories and files can add direct grants or establish a restricted boundary that ignores inherited permissions.
Supported URIs
ACL applies only to shared resources:
viking://resources/...
- An account
ADMINimplicitly hasmanageonviking://resources/.... viking://resourceshas a fixed, immutableuser:* = manageACL. Descendants inherit it until a restricted boundary.viking://user/{user_id}/resources/...is private and does not accept ACLs. To share it, move the resource into a writable shared directory and inherit that directory's ACL.
Implicit management is not stored as an ACL entry and cannot be removed by ACL changes. It ensures that shared resources always have an identity that can establish or recover permissions.
Principals and Levels
ACL entries use typed principals:
user:{user_id}: a user in the current account.group:{group_id}: a caller-supplied, account-unique group ID.user:*: any user in the current account.
group:* is not supported. Groups are flat. Membership changes do not rewrite resource ACL or context records; they take effect when the next request builds RequestContext.group_ids.
Asynchronous parse and semantic tasks created by a request carry the same group identity. After an add-resource destination write has been authorized, automatic semantic maintenance preserves that identity and uses an explicit internal ACL bypass instead of changing the caller's role.
| Level | Allowed operations |
|---|---|
read |
Read, list, and find/search/grep |
write |
read capabilities plus write, create, and tag updates |
manage |
write capabilities plus file/directory delete/move and ACL management |
Each higher level includes the lower levels. A manage grant therefore includes read and write.
Inheritance
A normal node combines direct and inherited grants. A restricted node uses only direct grants:
effective(node) = direct(node) + (acl_mode(node) == "restricted" ? empty : inherited(node))
inherited(node) always stores the parent's current effective permissions. It continues to refresh while the node is restricted, and disabling restricted mode applies the latest inherited value immediately. Descendants inherit the current node's effective permissions, so they cannot bypass an intermediate restricted boundary.
For example, first make A restricted to cut off the root wildcard grant, then configure:
read user:bob on viking://resources/A
write group:engineering on viking://resources/A/B
read user:carol on viking://resources/A/B/C/report.md
The effective permissions on report.md are:
- Bob:
read - Members of
engineering:write - Carol:
read
If A/B becomes restricted, Bob's grant on A no longer applies to A/B or its descendants, but the stored inherited value is not deleted. Disabling restricted mode immediately restores Bob's inherited access.
Default Behavior and acl_mode
The account-level acl.enabled setting is disabled by default. While disabled,
shared resources keep the existing URI namespace visibility and write rules.
ACL is not enforced. Indexed content still stores ACL fields using the same inheritance rules; the switch only controls access checks and retrieval filtering.
When enabled, the root grants user:* = manage, so all account members can
manage shared content that continues to inherit from the root. Without acl, new nodes have
empty direct ACLs and inherit their parent’s effective permissions. Creating
content grants no additional permissions. Import roots and descendants follow
the same rule. Existing shared content without ACL fields uses default
inheritance without a historical data migration. Disabling the setting stops
enforcing existing ACLs. Re-embedding or replacing an existing context record
does not change its direct ACL unless explicitly supplied. See ACL API for creation parameters.
acl_mode describes a resource's ACL behavior, separately from the account-wide acl.enabled switch:
none: ACL fields have not been materialized; shared nodes use default inheritance when ACL is enabled.inherit: use direct grants and permissions inherited from the parent.restricted: use direct grants only, while retaining and refreshing inherited grants.
Users with manage can switch between inherit and restricted, but cannot set none to bypass the parent's ACL. Exiting restricted mode restores parent inheritance; all account members regain manage when no other restricted boundary interrupts the path to the root. A restricted node with no direct grants remains protected, as do descendants without separate grants; account administrators retain implicit management access.
File Operations
All filesystem APIs use the same permission mapping:
| Operation | Required capability |
|---|---|
| read, stat, list, tree, find, search, grep, glob | read |
| write, create, mkdir, set tags | write |
| delete or move a file | manage |
| delete or move a directory | manage on that directory, authorizing its entire subtree including restricted descendants |
| manage ACL | manage |
| copy or move destination | write on the parent for a new path; write on an existing file; manage on an existing directory |
The server canonicalizes the URI, then uses one authorization entry point for account/owner/actor-peer boundaries, effective ACLs when enabled or existing namespace rules when disabled, and write/delete namespace guards.
When the account enables acl.enabled, ordinary shared nodes inherit the root’s
user:* = manage grant, allowing members to manage their ACLs. Creating content
inside a restricted directory only inherits the parent’s permissions.
An ACL grant on a directory is inherited by every descendant. list, tree, and other batch results still check every returned node because an open directory can contain independently restricted descendants.
Copies and moves do not carry source ACLs: existing destinations retain their ACLs, new destinations inherit their destination parent’s ACL, and private destinations have no ACL.
Delete and move authorize the specified file or directory without checking descendants individually. Copy queries for unreadable records within the directory and rejects the whole copy after confirming the path exists and its current ACL denies read access; destination descendants are not checked individually. Recursive tag updates still validate the complete subtree and stop on insufficient permission or an incomplete scan.
For a directory, stat.count uses the same path and ACL scalar filter and reports the number of context records visible to the caller.
Listing summaries reuse read authorization already completed for that page, without querying ACL again for each entry.
Retrieval Filtering
ACL data exists only in the context collection. Each context record stores direct and inherited permissions in native scalar fields:
acl_mode
acl_direct_grants
acl_inherited_grants
acl_direct_grants is the ACL assigned to the current node. acl_inherited_grants stores the parent's current effective ACL. acl_mode controls whether inherited grants contribute to the current node's effective permissions. Each principal stores only its highest level as {mask}:{principal}: 1 means read, 3 means write, and 7 means manage. There is no separate ACL collection.
ACLs update with the index, so records for the same URI may temporarily hold different versions. Reads use one ACL snapshot returned by the index, without merging grants across versions or blocking on temporary disagreement. Permission changes take effect as index updates complete; strong consistency is not guaranteed.
The request principals are user:{ctx.user_id}, user:*, and one group:{group_id} for each ID in ctx.group_ids. Within the shared scope, retrieval identifies controlled records with acl_mode IN [inherit, restricted], then matches each principal's 1, 3, and 7 grant tokens: direct or inherited for inherit mode, direct only for restricted mode. Shared records with missing, null, or none modes use the root’s default wildcard access in retrieval. Stored inherit nodes must match their direct or inherited grants; inherit mode alone never grants wildcard access. Private resources remain isolated by URI owner.
A retrieval target URI is only a search scope; the caller does not need to read the target node itself. A user can discover a deeply shared file even when intermediate directories are not readable.
When the account enables acl.enabled, shared-scope context writes preserve an
existing direct ACL for the same URI. New nodes have empty direct ACLs and
derive inherited ACL fields from their parent, including 7:user:* when no
restricted boundary intervenes. Creator identity does not affect authorization.
Re-embedding and ordinary replacement writes cannot reset controlled records to
default visibility or modify ACLs through regular context fields. When the
account disables the switch, retrieval uses only the original account and URI
scope filters and ignores these ACL fields.
Example
Assume project-a is already restricted and the caller has manage on it.
Grant Bob read-only access to the directory:
ov acl grant viking://resources/project-a --principal user:bob --level read
Bob can read and retrieve descendants, but cannot write or delete them. Upgrade the grant to write:
ov acl grant viking://resources/project-a --principal user:bob --level write
Remove Bob's direct grant from this node:
ov acl revoke viking://resources/project-a --principal user:bob
If an ancestor still grants Bob access, that inherited permission remains effective.
Use only direct grants on the current node while preserving and refreshing inherited grants:
ov acl set viking://resources/project-a --acl-mode restricted
Related Documentation
- ACL API - HTTP, SDK, and CLI interfaces
- Multi-Tenant - Account, user, and role boundaries
- Viking URI - URI namespaces
- Retrieval - Hierarchical retrieval flow