Skip to content

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

14.3 KB
Raw Blame
"""Namespace helpers for account/user/session URIs."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Optional

from openviking.core.identifiers import validate_user_id
from openviking.core.peer_id import normalize_peer_id
from openviking.server.identity import RequestContext, Role
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.uri import VikingURI

_CONTENT_TYPES_BY_SCOPE = {
    "user": {"memories": "memory", "resources": "resource", "skills": "skill"},
    "agent": {"skills": "skill"},
    "system": {"example-skills": "skill"},
}
_PEER_CONTENT_SEGMENTS = frozenset({"memories", "resources"})
_USER_RELATIVE_ROOT_SEGMENTS = frozenset({"peers", "privacy", "sessions"})
_CONTENT_SEGMENT_BY_KIND = {"resource": "resources", "skill": "skills"}


class NamespaceShapeError(ValueError):
    """Raised when a URI does not match the supported namespace shape."""


@dataclass(frozen=True)
class ResolvedNamespace:
    """Namespace information parsed from a canonical URI."""

    uri: str
    scope: str
    owner_user_id: Optional[str] = None
    is_container: bool = False


@dataclass(frozen=True)
class UriClassification:
    """Viking URI classification derived from path structure."""

    parts: tuple[str, ...]
    scope: str
    content_index: Optional[int]
    context_type: str

    @property
    def is_memory(self) -> bool:
        return self.context_type == "memory"

    @property
    def is_skill(self) -> bool:
        return self.context_type == "skill"

    @property
    def is_system(self) -> bool:
        return self.scope == "system"

    @property
    def is_user_namespace_root(self) -> bool:
        return _is_namespace_root_parts(self.parts, "user")

    @property
    def is_memory_root(self) -> bool:
        return (
            self.is_memory
            and self.content_index is not None
            and len(self.parts) == self.content_index + 1
        )

    @property
    def is_skill_namespace(self) -> bool:
        return (
            self.is_skill
            and self.content_index is not None
            and len(self.parts) == self.content_index + 1
        )

    @property
    def is_skill_root(self) -> bool:
        return (
            self.is_skill
            and self.content_index is not None
            and len(self.parts) == self.content_index + 2
        )


def uri_parts(uri: str) -> list[str]:
    """Return canonical Viking URI path segments without query parameters."""
    normalized = uri.split("?", 1)[0]
    if not normalized.startswith("viking://"):
        raise ValueError("URI must start with 'viking://'")
    if normalized == "viking://":
        return []
    normalized = normalized.rstrip("/")
    return [part for part in normalized[len("viking://") :].split("/") if part]


def uri_depth(uri: str) -> int:
    """Return the number of normalized Viking URI path segments."""
    return len(uri_parts(uri))


def uri_leaf_name(uri: str) -> str:
    """Return the final normalized Viking URI path segment."""
    parts = uri_parts(uri)
    return parts[-1] if parts else ""


def relative_uri_path(root_uri: str, uri: str) -> str:
    """Return uri's slash-separated path relative to root_uri, or empty when not nested."""
    root_parts = uri_parts(root_uri)
    parts = uri_parts(uri)
    if parts == root_parts or parts[: len(root_parts)] != root_parts:
        return ""
    return "/".join(parts[len(root_parts) :])


def _content_segment_index(parts: tuple[str, ...]) -> Optional[int]:
    """Return the content segment for a supported namespace shape."""
    if len(parts) >= 2 and parts[:2] == ("agent", "skills"):
        return 1
    if len(parts) >= 3 and parts[:3] == ("system", "compile", "example-skills"):
        return 2
    if len(parts) < 2 or parts[0] != "user":
        return None
    if len(parts) >= 5 and parts[2] == "peers" and parts[4] in _PEER_CONTENT_SEGMENTS:
        return 4
    if len(parts) >= 3 and parts[2] in _CONTENT_TYPES_BY_SCOPE["user"]:
        return 2
    return None


def _is_namespace_root_parts(parts: tuple[str, ...], scope: str) -> bool:
    return scope == "user" and parts[:1] == ("user",) and len(parts) == 2


def classify_uri(uri: str) -> UriClassification:
    parts = tuple(uri_parts(uri))
    content_index = _content_segment_index(parts)
    context_type = "resource"
    if content_index is not None:
        context_type = _CONTENT_TYPES_BY_SCOPE.get(parts[0], {}).get(
            parts[content_index], "resource"
        )
    return UriClassification(
        parts=parts,
        scope=parts[0] if parts else "",
        content_index=content_index,
        context_type=context_type,
    )


def context_type_for_uri(uri: str) -> str:
    return classify_uri(uri).context_type


def canonical_user_root(ctx: RequestContext) -> str:
    return f"viking://user/{user_space_fragment(ctx)}"


def user_space_fragment(ctx: RequestContext) -> str:
    return ctx.user.user_id


def canonical_session_root(ctx: RequestContext) -> str:
    return f"{canonical_user_root(ctx)}/sessions"


def canonical_session_uri(ctx: RequestContext, session_id: Optional[str] = None) -> str:
    root = canonical_session_root(ctx)
    if not session_id:
        return root
    return f"{root}/{session_id}"


def is_session_uri(uri: str) -> bool:
    parts = uri_parts(uri)
    return len(parts) >= 3 and parts[0] == "user" and parts[2] == "sessions"


AGENT_SKILLS_ROOT = "viking://agent/skills"


def visible_roots(ctx: RequestContext) -> list[str]:
    return [
        "viking://resources",
        "viking://agent",
        canonical_user_root(ctx),
    ]


def is_hidden_by_actor_peer_view(uri: str, ctx: RequestContext) -> bool:
    """Return whether uri points to another peer hidden by the actor peer view."""
    suffix = _actor_peer_view_user_suffix(uri, ctx)
    return bool(
        suffix and len(suffix) >= 2 and suffix[0] == "peers" and suffix[1] != ctx.actor_peer_id
    )


def may_include_hidden_actor_peers(uri: str, ctx: RequestContext) -> bool:
    """Return whether recursive data under uri may include hidden peers."""
    suffix = _actor_peer_view_user_suffix(uri, ctx)
    return suffix is not None and (not suffix or suffix == ["peers"])


def _actor_peer_view_user_suffix(uri: str, ctx: RequestContext) -> Optional[list[str]]:
    """Return uri's suffix under the current user root when actor peer view is active.

    The actor peer view filters only the current user's ``peers`` collection.
    It applies to filesystem and retrieval views, but does not change
    tenant/user identity or hide non-peer user content.
    """
    if not ctx.actor_peer_id:
        return None
    try:
        resolve_uri(uri)
    except NamespaceShapeError:
        return None
    parts = uri_parts(uri)
    user_root_parts = ["user", ctx.user.user_id]
    if parts[: len(user_root_parts)] != user_root_parts:
        return None
    return parts[len(user_root_parts) :]


def resolve_uri(
    uri: str,
) -> ResolvedNamespace:
    """Parse a canonical URI into its namespace and owner tuple."""

    parsed = VikingURI(uri)
    canonical_uri = parsed.uri.rstrip("/") or "viking://"
    parts = uri_parts(uri)
    if not parts:
        return ResolvedNamespace(uri="viking://", scope="", is_container=True)

    scope = parts[0]
    if scope == "user":
        return _resolve_user_uri(parts)
    if scope == "agent":
        return ResolvedNamespace(uri=canonical_uri, scope=scope)
    if scope == "~":
        # The home alias is expanded at the request boundary only. Reaching the
        # canonical parser with it (internal callers or storage paths) means no
        # identity is available, so fail closed instead of creating a literal
        # '~' namespace.
        raise NamespaceShapeError(f"Home alias URI is not canonical: {'/'.join(parts)}")
    if scope == "session":
        raise NamespaceShapeError(f"Legacy session URI is not canonical: {'/'.join(parts)}")
    if scope in {"resources", "temp", "queue", "upload"}:
        return ResolvedNamespace(uri=canonical_uri, scope=scope)
    return ResolvedNamespace(uri=canonical_uri, scope=scope)


def resolve_request_uri(uri: str, ctx: RequestContext) -> str:
    """Resolve supported URI aliases at an authenticated request boundary.

    The ``~`` home alias resolves to the authenticated user's namespace.
    The uid-less ``viking://user/<reserved>`` shorthand is no longer expanded:
    it fails closed with a hint pointing at ``viking://~/...``.
    """
    # Every authenticated request context carries an effective user identity,
    # including ROOT contexts produced by dev, API-key, and trusted auth modes.
    # Resolve the home alias for every role; keep the role-dependent handling
    # of ambiguous uid-less user paths below.
    parts = uri_parts(uri)
    if parts and parts[0] == "~":
        return resolve_current_user_uri(uri, ctx)
    if ctx.role in {Role.USER, Role.ADMIN}:
        return resolve_current_user_uri(uri, ctx)
    return resolve_uri(uri).uri


def resolve_current_user_uri(uri: str, ctx: RequestContext) -> str:
    """Resolve a URI field whose contract explicitly denotes the current user.

    The supported alias is ``viking://~``. ``viking://user/<reserved-segment>`` used to
    expand to the caller's space; it now fails closed with a corrective hint,
    because the same spelling is a valid explicit-uid URI for a user literally
    named after the reserved segment.
    """
    parts = uri_parts(uri)
    if not parts:
        return "viking://"

    if parts[0] == "~":
        if len(parts) == 1:
            return canonical_user_root(ctx)
        return f"{canonical_user_root(ctx)}/{'/'.join(parts[1:])}"

    if (
        parts[0] == "user"
        and len(parts) >= 2
        # Self-id escape: a caller literally named e.g. "resources" keeps
        # viking://user/resources as their canonical root.
        and parts[1] != ctx.user.user_id
        and _is_reserved_user_root_segment(parts[1])
    ):
        rest = "/".join(parts[1:])
        raise NamespaceShapeError(
            f"'viking://user/{rest}' no longer expands to the current user's space: "
            f"'{parts[1]}' is a reserved name, not a user id. Use 'viking://~/{rest}' "
            f"for the current user, or 'viking://user/{{user_id}}/{rest}' for an "
            f"explicit user."
        )

    # Bare 'viking://user' and explicit-uid forms fall through to the canonical
    # parser; the bare form keeps container semantics (is_container=True).
    return resolve_uri(uri).uri


def is_accessible(uri: str, ctx: RequestContext) -> bool:
    if getattr(ctx.role, "value", ctx.role) == "root":
        return True

    try:
        target = resolve_uri(uri)
    except NamespaceShapeError:
        return False

    if target.scope in {"", "resources", "agent", "temp", "queue"}:
        return True
    if target.scope == "upload":
        return False
    if target.scope == "user":
        if target.owner_user_id and target.owner_user_id != ctx.user.user_id:
            return False
        return True
    return True


def is_content_root_uri(
    uri: str,
    *,
    kind: str,
) -> bool:
    try:
        resolve_uri(uri)
    except (ValueError, NamespaceShapeError):
        return False
    parts = uri_parts(uri)
    if kind == "resource" and parts == ["resources"]:
        return True
    classification = classify_uri(uri)
    return (
        classification.context_type == kind
        and classification.content_index is not None
        and len(parts) == classification.content_index + 1
    )

def _validate_peer_id_segments(parts: list[str]) -> None:
    if len(parts) >= 4 and parts[0] == "user" and parts[2] == "peers":
        _require_peer_id_segment(parts[3])


def _require_peer_id_segment(peer_id: str) -> None:
    try:
        if normalize_peer_id(peer_id) is None:
            raise ValueError("peer_id must not be empty")
    except ValueError as exc:
        raise NamespaceShapeError(str(exc)) from exc


def owner_fields_for_uri(
    uri: str,
) -> dict:
    try:
        resolved = resolve_uri(uri)
    except (ValueError, NamespaceShapeError):
        return {
            "uri": uri.rstrip("/"),
            "owner_user_id": None,
        }
    return {
        "uri": resolved.uri,
        "owner_user_id": resolved.owner_user_id,
    }


def content_owner_context_for_uri(uri: str, ctx: RequestContext) -> RequestContext:
    """Use the canonical URI owner for content writes performed with caller authority."""
    owner_user_id = owner_fields_for_uri(uri).get("owner_user_id")
    if not owner_user_id or owner_user_id == ctx.user.user_id:
        return ctx
    return RequestContext(
        user=UserIdentifier(ctx.account_id, owner_user_id),
        role=ctx.role,
        group_ids=ctx.group_ids,
        actor_peer_id=ctx.actor_peer_id,
        from_oauth=ctx.from_oauth,
        api_key=ctx.api_key,
        bypass_acl=ctx.bypass_acl,
    )


def owner_space_for_uri(uri: str) -> str:
    """Derive the legacy owner_space bucket from the canonical URI owner."""
    resolved = resolve_uri(uri)
    if resolved.scope == "user" and resolved.owner_user_id:
        return resolved.owner_user_id
    return ""


def _resolve_user_uri(
    parts: list[str],
) -> ResolvedNamespace:
    if len(parts) == 1:
        return ResolvedNamespace(uri="viking://user", scope="user", is_container=True)

    second = parts[1]
    user_id = second
    validation_error = validate_user_id(user_id)
    if validation_error:
        raise NamespaceShapeError(f"Invalid user_id: {validation_error}")
    if len(parts) == 2:
        return ResolvedNamespace(
            uri=f"viking://user/{user_id}",
            scope="user",
            owner_user_id=user_id,
        )

    suffix = parts[2:]
    canonical = f"viking://user/{user_id}"
    if suffix:
        canonical = f"{canonical}/{'/'.join(suffix)}"
    _validate_peer_id_segments(parts)
    return ResolvedNamespace(
        uri=canonical,
        scope="user",
        owner_user_id=user_id,
    )


def _is_reserved_user_root_segment(segment: str) -> bool:
    """Return whether a first-level user segment is a reserved space name.

    Reserved names (``memories``, ``resources``, ``skills``, ``peers``,
    ``privacy``, ``sessions``) are rejected at request boundaries when they
    appear without an explicit user id, because they are ambiguous with a user
    literally named after them.
    """
    return segment in _CONTENT_TYPES_BY_SCOPE["user"] or segment in _USER_RELATIVE_ROOT_SEGMENTS