Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

23.4 KB
Raw Blame
"""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],
        }