Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
"""Context-backed ACL storage and permission resolution."""
from __future__ import annotations
from dataclasses import dataclass, replace
from enum import Enum
from typing import TYPE_CHECKING, Any, AsyncIterator, Iterable, Literal, Mapping, Protocol, Sequence
from pydantic import BaseModel, ConfigDict, model_validator
from openviking.core.identifiers import validate_identifier_part, validate_user_id
from openviking.core.namespace import uri_parts
from openviking.server.identity import RequestContext, Role
from openviking.storage.expr import And, Eq, FilterExpr, In, Or, PathScope, RawDSL
from openviking_cli.exceptions import InvalidArgumentError
if TYPE_CHECKING:
from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend
class AccountConfigReader(Protocol):
async def get_account(self, account_id: str, field: str) -> Any: ...
class AclLevel(str, Enum):
READ = "read"
WRITE = "write"
MANAGE = "manage"
class AclAction(str, Enum):
READ = "read"
WRITE = "write"
MANAGE = "manage"
class AclMode(str, Enum):
NONE = "none"
INHERIT = "inherit"
RESTRICTED = "restricted"
_LEVEL_MASK = {
AclLevel.READ: 1,
AclLevel.WRITE: 3,
AclLevel.MANAGE: 7,
}
_MASK_LEVEL = {mask: level for level, mask in _LEVEL_MASK.items()}
ACL_GRANT_FIELDS = ("acl_direct_grants", "acl_inherited_grants")
ACL_MODE_FIELD = "acl_mode"
ACL_CONTEXT_FIELDS = frozenset((ACL_MODE_FIELD, *ACL_GRANT_FIELDS))
_ACL_OUTPUT_FIELDS = ["uri", *sorted(ACL_CONTEXT_FIELDS)]
@dataclass(frozen=True)
class AclEntry:
principal: str
level: AclLevel
def to_dict(self) -> dict[str, str]:
return {"principal": self.principal, "level": self.level.value}
class AclSpec(BaseModel):
"""Explicit changes to a node's own permissions, never inherited grants."""
model_config = ConfigDict(extra="forbid", frozen=True)
entries: tuple[AclEntry, ...] | None = None
acl_mode: Literal[AclMode.INHERIT, AclMode.RESTRICTED] | None = None
@model_validator(mode="after")
def normalize(self) -> "AclSpec":
if self.entries is None and self.acl_mode is None:
raise ValueError("entries or acl_mode must be provided")
if self.entries is not None:
object.__setattr__(self, "entries", tuple(_normalize_entries(self.entries)))
return self
class AclUpdate(BaseModel):
"""An authorized ACL change bound to its final target URI."""
model_config = ConfigDict(extra="forbid", frozen=True)
uri: str
acl: AclSpec
@dataclass(frozen=True)
class DirectAcl:
entries: tuple[AclEntry, ...] = ()
@classmethod
def from_entries(cls, entries: Iterable[AclEntry | Mapping[str, Any]]) -> "DirectAcl":
return cls(tuple(_normalize_entries(entries)))
@property
def empty(self) -> bool:
return not self.entries
def union(self, other: "DirectAcl") -> "DirectAcl":
return DirectAcl.from_entries((*self.entries, *other.entries))
def principals_for(self, action: AclAction) -> frozenset[str]:
required_mask = _LEVEL_MASK[AclLevel(action.value)]
return frozenset(
entry.principal
for entry in self.entries
if _LEVEL_MASK[entry.level] & required_mask == required_mask
)
def context_fields(self, prefix: str) -> dict[str, Any]:
return {f"{prefix}_grants": [_encode_grant(entry) for entry in self.entries]}
@classmethod
def from_context_fields(cls, record: Mapping[str, Any], prefix: str) -> "DirectAcl":
raw_grants = record.get(f"{prefix}_grants") or []
if not isinstance(raw_grants, (list, tuple)):
raise RuntimeError(f"Invalid ACL grants for {prefix}: expected a list")
# ponytail: 兼容离线索引将空 ACL list 还原为空字符串元素;只忽略精确空串,
# 其他非法 token 仍由 _decode_grant 拒绝。底层稳定保留 [] 后应删除。
raw_grants = [grant for grant in raw_grants if grant != ""]
return cls.from_entries(_decode_grant(grant) for grant in raw_grants)
@dataclass(frozen=True)
class EffectiveAcl:
mode: AclMode
direct: DirectAcl
inherited: DirectAcl
@classmethod
def from_permissions(
cls,
direct: DirectAcl,
inherited: DirectAcl,
*,
mode: AclMode = AclMode.NONE,
parent_mode: AclMode = AclMode.NONE,
) -> "EffectiveAcl":
if mode != AclMode.RESTRICTED:
# A restricted ancestor can protect descendants even with no grants.
mode = (
AclMode.INHERIT
if parent_mode != AclMode.NONE or not direct.empty or not inherited.empty
else AclMode.NONE
)
return cls(mode, direct, inherited)
@property
def enabled(self) -> bool:
return self.mode != AclMode.NONE
@property
def permissions(self) -> DirectAcl:
if self.mode == AclMode.RESTRICTED:
return self.direct
return self.inherited.union(self.direct)
def context_fields(self) -> dict[str, Any]:
return {
ACL_MODE_FIELD: self.mode.value,
**self.direct.context_fields("acl_direct"),
**self.inherited.context_fields("acl_inherited"),
}
_RESOURCES_ROOT_ACL = EffectiveAcl(
AclMode.INHERIT,
DirectAcl((AclEntry("user:*", AclLevel.MANAGE),)),
DirectAcl(),
)
def normalize_acl_principal(principal: Any) -> str:
if not isinstance(principal, str):
raise InvalidArgumentError("principal must be a string")
normalized = principal.strip()
kind, separator, identifier = normalized.partition(":")
if not separator or kind not in {"user", "group"}:
raise InvalidArgumentError("principal must use user:<id> or group:<id>")
if kind == "user":
if identifier != "*":
error = validate_user_id(identifier)
if error:
raise InvalidArgumentError(error)
else:
if identifier == "*":
raise InvalidArgumentError("group:* is not supported")
error = validate_identifier_part(identifier, "group_id")
if error:
raise InvalidArgumentError(error)
return normalized
def acl_principals(ctx: RequestContext) -> frozenset[str]:
return frozenset(
[
f"user:{ctx.user.user_id}",
"user:*",
*(f"group:{value}" for value in ctx.group_ids),
]
)
def normalize_acl_level(value: Any) -> AclLevel:
if isinstance(value, AclLevel):
return value
try:
return AclLevel(str(value).strip())
except ValueError as exc:
raise InvalidArgumentError("ACL level must be read, write, or manage") from exc
def _encode_grant(entry: AclEntry) -> str:
return f"{_LEVEL_MASK[entry.level]}:{entry.principal}"
def _decode_grant(raw: Any) -> AclEntry:
if not isinstance(raw, str):
raise RuntimeError("Invalid ACL grant token: expected a string")
raw_mask, separator, raw_principal = raw.partition(":")
try:
level = _MASK_LEVEL[int(raw_mask)] if separator else None
principal = normalize_acl_principal(raw_principal)
except (InvalidArgumentError, KeyError, ValueError) as exc:
raise RuntimeError(f"Invalid ACL grant token: {raw!r}") from exc
if level is None or raw != _encode_grant(AclEntry(principal, level)):
raise RuntimeError(f"Invalid ACL grant token: {raw!r}")
return AclEntry(principal, level)
def acl_grant_tokens(principals: Iterable[str], action: AclAction) -> list[str]:
"""Return exact scalar-index tokens that satisfy *action* for the principals."""
required_mask = _LEVEL_MASK[AclLevel(action.value)]
return [
_encode_grant(AclEntry(principal, level))
for principal in sorted(set(principals))
for level, mask in _LEVEL_MASK.items()
if mask & required_mask == required_mask
]
def acl_filter(ctx: RequestContext, action: AclAction, *, denied: bool = False) -> FilterExpr:
"""Filter shared-resource ACL records; callers handle role and namespace bypasses."""
grants = acl_grant_tokens(acl_principals(ctx), action)
controlled_modes = [AclMode.INHERIT.value, AclMode.RESTRICTED.value]
grant_op = "must_not" if denied else "must"
direct = RawDSL({"op": grant_op, "field": "acl_direct_grants", "conds": grants})
inherited = RawDSL({"op": grant_op, "field": "acl_inherited_grants", "conds": grants})
if denied:
return And(
[
In(ACL_MODE_FIELD, controlled_modes),
direct,
Or([Eq(ACL_MODE_FIELD, AclMode.RESTRICTED.value), inherited]),
]
)
# Uncontrolled records retain the shared root's default user:* manage grant.
return Or(
[
RawDSL({"op": "must_not", "field": ACL_MODE_FIELD, "conds": controlled_modes}),
direct,
And([Eq(ACL_MODE_FIELD, AclMode.INHERIT.value), inherited]),
]
)
def _normalize_entries(entries: Iterable[AclEntry | Mapping[str, Any]]) -> list[AclEntry]:
highest: dict[str, AclLevel] = {}
for raw in entries:
if isinstance(raw, AclEntry):
principal, raw_level = raw.principal, raw.level
else:
principal = raw.get("principal")
raw_level = raw.get("level", "")
principal = normalize_acl_principal(principal)
level = normalize_acl_level(raw_level)
current = highest.get(principal)
if current is None or _LEVEL_MASK[level] > _LEVEL_MASK[current]:
highest[principal] = level
return [AclEntry(principal, highest[principal]) for principal in sorted(highest)]
def is_acl_uri(uri: str) -> bool:
return uri_parts(uri)[:1] == ["resources"]
def acl_ancestors(uri: str) -> list[str]:
"""Return ACL-bearing ancestors from the resource root through *uri*."""
parts = uri_parts(uri)
if parts[:1] != ["resources"]:
raise InvalidArgumentError("ACL is only supported for viking://resources")
return [f"viking://{'/'.join(parts[:depth])}" for depth in range(1, len(parts) + 1)]
def has_implicit_manage(ctx: RequestContext, uri: str) -> bool:
return is_acl_uri(uri) and ctx.role == Role.ADMIN
def acl_allows(acl: EffectiveAcl, ctx: RequestContext, action: AclAction) -> bool:
principals = acl.permissions.principals_for(action)
return not principals.isdisjoint(acl_principals(ctx))
class AclManager:
"""Stores ACL state in the context collection."""
def __init__(
self,
context_store: "VikingVectorIndexBackend",
runtime_config: AccountConfigReader | None = None,
) -> None:
self._context_store = context_store
self._runtime_config = runtime_config
def set_runtime_config_manager(self, runtime_config: AccountConfigReader) -> None:
"""Bind the authoritative account configuration reader."""
self._runtime_config = runtime_config
async def is_enabled(self, account_id: str) -> bool:
"""Resolve the account ACL switch, loading its config on cache miss."""
if self._runtime_config is None:
raise RuntimeError("Runtime config manager is not initialized")
setting = await self._runtime_config.get_account(account_id, "acl")
return False if setting is None else bool(setting.enabled)
@staticmethod
def _effective_from_record(record: Mapping[str, Any]) -> EffectiveAcl:
direct = DirectAcl.from_context_fields(record, "acl_direct")
inherited = DirectAcl.from_context_fields(record, "acl_inherited")
raw_mode = record.get(ACL_MODE_FIELD, AclMode.NONE.value)
if raw_mode is None:
raw_mode = AclMode.NONE.value
try:
mode = AclMode(raw_mode)
except (TypeError, ValueError) as exc:
raise RuntimeError(f"Invalid ACL mode: {raw_mode!r}") from exc
return EffectiveAcl(
mode=mode,
direct=direct,
inherited=inherited,
)
@classmethod
def _effective_from_records(cls, records: Sequence[Mapping[str, Any]]) -> EffectiveAcl:
if not records:
return EffectiveAcl(AclMode.NONE, DirectAcl(), DirectAcl())
# Index records refresh independently. Read one ACL snapshot rather than
# combining grants from different versions or blocking on disagreement.
return cls._effective_from_record(records[0])
@staticmethod
def _group_by_uri(records: Sequence[Mapping[str, Any]]) -> dict[str, list[Mapping[str, Any]]]:
grouped: dict[str, list[Mapping[str, Any]]] = {}
for record in records:
uri = record.get("uri")
if uri:
grouped.setdefault(str(uri), []).append(record)
return grouped
async def _records_for_uris(
self,
uris: Iterable[str],
ctx: RequestContext,
) -> list[dict[str, Any]]:
unique = sorted(set(uris))
records: list[dict[str, Any]] = []
for offset in range(0, len(unique), 100):
conditions = [PathScope("uri", uri, depth=0) for uri in unique[offset : offset + 100]]
records.extend(
await self._scroll_all(Or(conditions), _ACL_OUTPUT_FIELDS, ctx)
)
return records
async def _scroll_all(
self,
filter_expr: FilterExpr,
output_fields: list[str],
ctx: RequestContext,
) -> list[dict[str, Any]]:
records: list[dict[str, Any]] = []
cursor: str | None = None
while True:
page, cursor = await self._context_store.scroll(
filter=filter_expr,
limit=500,
cursor=cursor,
output_fields=output_fields,
# ACL resolution must see records the caller's own grants hide.
ctx=replace(ctx, bypass_acl=True),
)
records.extend(page)
if cursor is None:
return records
async def iter_denied_uris(
self, uri: str, ctx: RequestContext, *, action: AclAction
) -> AsyncIterator[str]:
"""Find denied records in a subtree, validating each URI's current ACL snapshot."""
scope = And(
[
Eq("account_id", ctx.account_id),
PathScope("uri", uri, depth=-1),
acl_filter(ctx, action, denied=True),
]
)
cursor: str | None = None
checked: set[str] = set()
while True:
records, cursor = await self._context_store.scroll(
filter=scope,
limit=1,
cursor=cursor,
output_fields=["uri"],
ctx=replace(ctx, bypass_acl=True),
)
for record in records:
candidate = record["uri"]
if candidate in checked:
continue
checked.add(candidate)
# Index levels can carry older snapshots for the same path.
if not acl_allows(await self.resolve(candidate, ctx), ctx, action):
yield candidate
if cursor is None:
return
async def _subtree_records(self, uri: str, ctx: RequestContext) -> list[dict[str, Any]]:
refs = await self._scroll_all(PathScope("uri", uri, depth=-1), ["id"], ctx)
ids = [str(record["id"]) for record in refs if record.get("id")]
records: list[dict[str, Any]] = []
for offset in range(0, len(ids), 500):
records.extend(
await self._context_store.get_strict(ids[offset : offset + 500], ctx=ctx)
)
return records
async def get_direct(self, uri: str, ctx: RequestContext) -> DirectAcl:
return (await self.resolve(uri, ctx)).direct
async def resolve_many(
self, uris: Iterable[str], ctx: RequestContext, *, update: AclUpdate | None = None
) -> dict[str, EffectiveAcl]:
unique_uris = list(dict.fromkeys(uris))
ancestors_by_uri = {uri: acl_ancestors(uri) for uri in unique_uris}
exact_records = await self._records_for_uris(unique_uris, ctx)
exact_groups = self._group_by_uri(exact_records)
result: dict[str, EffectiveAcl] = {}
for uri, records in exact_groups.items():
effective = self._effective_from_records(records)
if not effective.enabled:
continue
# An update to this node or an ancestor requires recalculating inheritance.
if update is not None and update.uri in ancestors_by_uri[uri]:
continue
result[uri] = effective
if "viking://resources" in ancestors_by_uri:
result["viking://resources"] = _RESOURCES_ROOT_ACL
unresolved_uris = [uri for uri in unique_uris if uri not in result]
if unresolved_uris:
ancestor_records = await self._records_for_uris(
(ancestor for uri in unresolved_uris for ancestor in ancestors_by_uri[uri]), ctx
)
ancestor_groups = self._group_by_uri(ancestor_records)
acl_map = {
uri: self._effective_from_records(records)
for uri, records in ancestor_groups.items()
}
acl_map["viking://resources"] = _RESOURCES_ROOT_ACL
for uri in unresolved_uris:
effective = EffectiveAcl(AclMode.NONE, DirectAcl(), DirectAcl())
for ancestor in ancestors_by_uri[uri]:
stored = acl_map.get(ancestor)
direct = stored.direct if stored is not None else DirectAcl()
mode = stored.mode if stored is not None else AclMode.NONE
if update is not None and ancestor == update.uri:
if update.acl.entries is not None:
direct = DirectAcl.from_entries(update.acl.entries)
if update.acl.acl_mode is not None:
mode = update.acl.acl_mode
effective = EffectiveAcl.from_permissions(
direct,
effective.permissions,
mode=mode,
parent_mode=effective.mode,
)
result[uri] = effective
return result
async def resolve(self, uri: str, ctx: RequestContext) -> EffectiveAcl:
return (await self.resolve_many([uri], ctx))[uri]
async def materialize_context_records(
self,
records: Sequence[dict[str, Any]],
ctx: RequestContext,
*,
update: AclUpdate | None = None,
) -> list[dict[str, Any]]:
resource_uris: set[str] = set()
for record in records:
uri = record.get("uri")
if not uri:
continue
resource_uri = str(uri)
if not is_acl_uri(resource_uri):
continue
resource_uris.add(resource_uri)
if not resource_uris:
return list(records)
effective = await self.resolve_many(resource_uris, ctx, update=update)
return [
{**record, **effective[str(record["uri"])].context_fields()}
if str(record.get("uri") or "") in effective
else dict(record)
for record in records
]
async def _apply_subtree(
self,
root_uri: str,
records: Sequence[dict[str, Any]],
ctx: RequestContext,
*,
root_direct: DirectAcl | None = None,
root_mode: AclMode | None = None,
) -> EffectiveAcl:
grouped = self._group_by_uri(records)
if root_uri not in grouped:
raise InvalidArgumentError("ACL target has no context record; index it first")
stored_acl = {uri: self._effective_from_records(items) for uri, items in grouped.items()}
direct_map = {uri: effective.direct for uri, effective in stored_acl.items()}
mode_map = {uri: effective.mode for uri, effective in stored_acl.items()}
if root_direct is not None:
direct_map[root_uri] = root_direct
if root_mode is not None:
mode_map[root_uri] = root_mode
root_ancestors = acl_ancestors(root_uri)
parent = root_ancestors[-2] if len(root_ancestors) > 1 else None
base = (
await self.resolve(parent, ctx)
if parent
else EffectiveAcl(AclMode.NONE, DirectAcl(), DirectAcl())
)
effective_by_uri: dict[str, EffectiveAcl] = {}
root_depth = len(root_ancestors)
for uri in sorted(grouped, key=lambda value: len(acl_ancestors(value))):
if uri == "viking://resources":
effective_by_uri[uri] = _RESOURCES_ROOT_ACL
continue
ancestors = acl_ancestors(uri)
parent_effective = base
for ancestor in ancestors[root_depth - 1 : -1]:
parent_effective = effective_by_uri.get(ancestor, parent_effective)
inherited = parent_effective.permissions
direct = direct_map.get(uri, DirectAcl())
effective_by_uri[uri] = EffectiveAcl.from_permissions(
direct, inherited, mode=mode_map[uri], parent_mode=parent_effective.mode
)
updated = [
{**record, **effective_by_uri[str(record["uri"])].context_fields()}
for record in records
if str(record.get("uri") or "") in effective_by_uri
]
ids = await self._context_store._upsert_many_raw(updated, ctx=ctx)
if len(ids) != len(updated):
raise RuntimeError(f"Failed to update {len(updated) - len(ids)} context ACL record(s)")
return effective_by_uri[root_uri]
async def refresh_context_subtree(self, uri: str, ctx: RequestContext) -> None:
records = await self._subtree_records(uri, ctx)
if records:
await self._apply_subtree(uri, records, ctx)
async def apply_indexed_update(self, update: AclUpdate, ctx: RequestContext) -> None:
"""Apply an authorized ingestion update when the target is already indexed."""
if await self._records_for_uris([update.uri], ctx):
await self.set_acl(update.uri, update.acl.entries, ctx, acl_mode=update.acl.acl_mode)
async def set_acl(
self,
uri: str,
entries: Sequence[AclEntry | Mapping[str, Any]] | None,
ctx: RequestContext,
*,
acl_mode: AclMode | None = None,
) -> EffectiveAcl:
if uri_parts(uri) == ["resources"]:
raise InvalidArgumentError("ACL cannot be set on viking://resources")
if entries is None and acl_mode is None:
raise InvalidArgumentError("entries or acl_mode must be provided")
proposed_direct = DirectAcl.from_entries(entries) if entries is not None else None
old_records = await self._subtree_records(uri, ctx)
try:
effective = await self._apply_subtree(
uri,
old_records,
ctx,
root_direct=proposed_direct,
root_mode=acl_mode,
)
except Exception:
if old_records:
await self._context_store._upsert_many_raw(old_records, ctx=ctx)
raise
return effective
@staticmethod
def to_report(uri: str, effective: EffectiveAcl) -> dict[str, Any]:
return {
"uri": uri,
ACL_MODE_FIELD: effective.mode.value,
"direct_entries": [entry.to_dict() for entry in effective.direct.entries],
"inherited_entries": [entry.to_dict() for entry in effective.inherited.entries],
"effective_entries": [entry.to_dict() for entry in effective.permissions.entries],
}