satchel-server 0.1.1__py3-none-any.whl

satchel/api/app.py

@@ -0,0 +1,207 @@
+"""REST API (design §2, §14 M1/M3a): library, workbench, proposals, observability, catalog.
+
+Everything is under ``/v1`` with role enforcement per design §9 (admin > curator > analyst >
+explorer). The OAuth authorization server and OIDC login routes and ``/mcp`` are mounted here
+too. Auth lives in :mod:`satchel.api.auth`; routers in the sibling modules. ``/openapi.json`` is
+the contract the web UI generates its TypeScript types from (``satchel openapi``).
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, FastAPI, HTTPException
+from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.routing import APIRoute
+from sqlalchemy import Engine, select
+
+from satchel.api import (
+    audit,
+    catalog,
+    connections,
+    evals,
+    hooks,
+    library,
+    llm,
+    observability,
+    proposals,
+    sources,
+    suggestions,
+    workbench,
+    workspace_settings,
+)
+from satchel.api.auth import ApiContext, Auth, Caller
+from satchel.api.health import mount_readyz
+from satchel.api.schemas import (
+    MeOut,
+    PackEntryOut,
+    PackOut,
+    PackRequest,
+    SearchHitOut,
+    SearchRequest,
+)
+from satchel.llm.chat import ChatProvider
+from satchel.llm.embeddings import EmbeddingProvider, make_embedder
+from satchel.oauth.clients import CimdFetcher
+from satchel.oauth.oidc import OidcProvider
+from satchel.oauth.routes import OAuthApp, mount_oauth
+from satchel.retrieval import build_context_pack, search_context
+from satchel.runtime import TraceMiddleware
+from satchel.settings import Settings, get_settings
+from satchel.store.db import admin_session, get_engine, workspace_session
+from satchel.store.models import AppUser, Workspace
+
+__all__ = ["Caller", "create_app"]
+
+
+# Paths the SPA fallback must never answer (they are APIs, so a miss is a real 404).
+_API_PREFIXES = (
+    "v1", "auth", "oauth", "mcp", ".well-known", "openapi.json", "docs", "redoc", "healthz",
+    "readyz",
+)
+_DEFAULT_UI_DIR = Path(__file__).resolve().parents[3] / "ui" / "dist"  # repo checkout
+_PACKAGED_UI_DIR = Path(__file__).resolve().parents[1] / "resources" / "ui"  # built into the wheel
+
+_NO_UI_PAGE = """<!doctype html><meta charset="utf-8"><title>satchel</title>
+<body style="font:15px/1.5 system-ui;max-width:640px;margin:48px auto;padding:0 16px">
+<h1>Satchel is running</h1>
+<p>The API and MCP endpoint are up, but this install has no built curator UI.</p>
+<p>The PyPI package includes it: <code>uv tool install --force satchel-server</code>.
+From a satchel repo checkout, build it and point satchel at it:</p>
+<pre>cd ui &amp;&amp; npm ci &amp;&amp; npm run build
+SATCHEL_UI_DIR=$PWD/dist satchel up</pre>
+<p>Or reinstall from the checkout after building, so the UI is bundled:
+<code>uv tool install --force ./server</code></p>
+<p>MCP: <code>/mcp</code> &middot; API docs: <a href="/docs">/docs</a></p></body>"""
+
+
+def _resolve_ui_dir(configured: str | None) -> Path | None:
+    """Configured dir, else the wheel's bundled UI, the repo checkout, or ./ui/dist."""
+    if configured:
+        return Path(configured).expanduser()
+    for cand in (_PACKAGED_UI_DIR, _DEFAULT_UI_DIR, Path.cwd() / "ui" / "dist"):
+        if (cand / "index.html").is_file():
+            return cand
+    return None
+
+
+def _mount_ui(app: FastAPI, ui_dir: Path) -> bool:
+    """Serve the built curator UI at ``/`` with an SPA fallback (registered last)."""
+    root = ui_dir.resolve()
+    index = root / "index.html"
+    if not index.is_file():
+        return False
+
+    @app.get("/{path:path}", include_in_schema=False)
+    def spa(path: str) -> FileResponse:
+        head = path.split("/", 1)[0]
+        if head in _API_PREFIXES:
+            raise HTTPException(404, "Not Found")
+        candidate = (root / path).resolve()
+        if path and candidate.is_file() and candidate.is_relative_to(root):
+            return FileResponse(candidate)
+        return FileResponse(index, headers={"Cache-Control": "no-cache"})
+
+    return True
+
+
+def _operation_id(route: APIRoute) -> str:
+    return route.name  # stable, readable names for the generated TS client
+
+
+def create_app(
+    engine: Engine | None = None, embedder: EmbeddingProvider | None = None, *,
+    mcp: bool = True, settings: Settings | None = None, oidc: OidcProvider | None = None,
+    cimd_fetcher: CimdFetcher | None = None, chat: ChatProvider | None = None,
+) -> FastAPI:
+    app = FastAPI(title="satchel", version="0.1.0", generate_unique_id_function=_operation_id)
+    app.add_middleware(TraceMiddleware)
+    eng = engine or get_engine()
+    emb = embedder or make_embedder()
+    st = settings or get_settings()
+    if mcp:
+        from satchel.mcp.http import McpHttp, mount_mcp
+
+        mount_mcp(app, McpHttp(eng, emb, st))  # Streamable HTTP at /mcp, bearer auth
+    mount_oauth(app, OAuthApp(eng, st, oidc, cimd_fetcher))  # /oauth/*, /auth/*, /.well-known/*
+
+    auth = Auth(ApiContext(eng, emb, st, chat))
+    Who = Annotated[Caller, Depends(auth.require("explorer"))]
+
+    @app.get("/healthz")
+    def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+
+    mount_readyz(app, eng)
+
+    me = APIRouter(tags=["me"])
+
+    @me.get("/v1/me", response_model=MeOut)
+    def get_me(who: Who) -> MeOut:
+        with admin_session(engine=eng) as s:
+            ws = s.scalars(select(Workspace).where(Workspace.id == who.workspace_id)).one()
+            u = s.get(AppUser, who.user_id) if who.user_id else None
+            return MeOut(
+                user_id=who.user_id, email=u.email if u else None,
+                name=u.display_name if u else None, role=who.effective_role,
+                workspace_id=ws.id, workspace_slug=ws.slug, workspace_name=ws.name,
+                csrf_token=who.csrf, auth=who.auth,
+            )
+
+    app.include_router(me)
+    app.include_router(library.make_router(auth))
+    app.include_router(workbench.make_router(auth))
+    app.include_router(proposals.make_router(auth))
+    app.include_router(suggestions.make_router(auth))
+    app.include_router(observability.make_router(auth))
+    app.include_router(catalog.make_router(auth))
+    app.include_router(evals.make_router(auth))
+    app.include_router(sources.make_router(auth))
+    app.include_router(hooks.make_router(auth.ctx))  # unauthenticated push webhooks
+    app.include_router(audit.make_router(auth))
+    app.include_router(llm.make_router(auth))
+    app.include_router(connections.make_router(auth))
+    app.include_router(workspace_settings.make_router(auth))
+
+    search_r = APIRouter(tags=["retrieval"])
+
+    @search_r.post("/v1/search", response_model=list[SearchHitOut])
+    def search(req: SearchRequest, who: Who) -> list[SearchHitOut]:
+        with workspace_session(who.workspace_id, who.user_id, engine=eng) as s:
+            hits = search_context(s, req.query, types=req.types, k=req.k, embedder=emb)
+            return [
+                SearchHitOut(
+                    key=h.key, type=h.type, seq=h.seq, tag=h.tag, score=h.score,
+                    sources=h.sources, snippet=h.snippet,
+                )
+                for h in hits
+            ]
+
+    @search_r.post("/v1/context-pack", response_model=PackOut)
+    def context_pack(req: PackRequest, who: Who) -> PackOut:
+        with workspace_session(who.workspace_id, who.user_id, engine=eng) as s:
+            pack = build_context_pack(
+                s, req.question, who.user_id, embedder=emb, budget_tokens=req.budget_tokens
+            )
+            return PackOut(
+                release_id=pack.release_id,
+                budget_tokens=pack.budget_tokens,
+                used_tokens=pack.used_tokens,
+                text=pack.text,
+                entries=[
+                    PackEntryOut(
+                        key=e.key, type=e.type, seq=e.seq, tag=e.tag, tokens=e.tokens,
+                        score=e.score, text=e.text,
+                    )
+                    for e in pack.entries
+                ],
+            )
+
+    app.include_router(search_r)
+    ui = _resolve_ui_dir(st.ui_dir)
+    if ui is None or not _mount_ui(app, ui):
+
+        @app.get("/", include_in_schema=False)
+        def no_ui() -> HTMLResponse:
+            return HTMLResponse(_NO_UI_PAGE)
+
+    return app

satchel/api/audit.py

@@ -0,0 +1,80 @@
+"""``GET /v1/audit``: the audit trail for SIEM pulls (admin, RLS-scoped, keyset paginated).
+
+Events are ordered by ``(created_at, id)``. Poll with ``since`` and follow ``next_cursor``
+until it is null; remember the last event's ``created_at`` as the next ``since``. For bulk
+export to files or object storage use ``satchel audit export``.
+"""
+
+from datetime import datetime
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
+
+from satchel import audit as audit_lib
+from satchel.api.auth import Auth, Caller
+from satchel.store.db import workspace_session
+
+
+class AuditEventOut(BaseModel):
+    id: int
+    workspace: str
+    actor_user_id: str | None
+    actor_email: str | None
+    action: str
+    target: dict[str, Any]
+    created_at: datetime
+
+
+class AuditPage(BaseModel):
+    events: list[AuditEventOut]
+    next_cursor: str | None = Field(
+        default=None, description="Pass as `cursor` for the next page; null on the last page."
+    )
+
+
+def _when(name: str, value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    try:
+        return audit_lib.parse_when(value)
+    except ValueError as e:
+        raise HTTPException(422, f"{name}: {e}") from None
+
+
+def make_router(auth: Auth) -> APIRouter:
+    r = APIRouter(tags=["audit"])
+    Adm = Annotated[Caller, Depends(auth.require("admin"))]
+    eng = auth.ctx.engine
+
+    @r.get("/v1/audit", response_model=AuditPage)
+    def list_audit(
+        who: Adm,
+        since: Annotated[str | None, Query(description="ISO-8601, inclusive")] = None,
+        until: Annotated[str | None, Query(description="ISO-8601, exclusive")] = None,
+        cursor: Annotated[str | None, Query(description="From a previous page")] = None,
+        limit: Annotated[int, Query(ge=1, le=1000)] = 500,
+    ) -> AuditPage:
+        after = None
+        if cursor is not None:
+            try:
+                after = audit_lib.decode_cursor(cursor)
+            except ValueError:
+                raise HTTPException(422, "invalid cursor") from None
+        with workspace_session(who.workspace_id, who.user_id, engine=eng) as s:
+            rows, nxt = audit_lib.fetch_page(
+                s, since=_when("since", since), until=_when("until", until), after=after,
+                limit=limit, workspace_id=who.workspace_id,
+            )
+            events = [
+                AuditEventOut(
+                    id=x.id, workspace=x.workspace,
+                    actor_user_id=str(x.actor_user_id) if x.actor_user_id else None,
+                    actor_email=x.actor_email, action=x.action, target=x.target,
+                    created_at=x.created_at,
+                )
+                for x in rows
+            ]
+        return AuditPage(events=events, next_cursor=audit_lib.encode_cursor(nxt) if nxt else None)
+
+    return r

satchel/api/auth.py

@@ -0,0 +1,133 @@
+"""REST authentication + role enforcement (design §9).
+
+Auth, first match wins: bearer PAT / OAuth access token; the ``satchel_session`` cookie (writes
+must echo ``X-CSRF-Token``); and only with ``SATCHEL_DEV_AUTH=1`` the unverified
+``X-Satchel-Workspace`` / ``X-Satchel-User`` headers. ``require(role)`` builds a dependency that
+also enforces a minimum role.
+"""
+
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Annotated
+
+from fastapi import Depends, Header, HTTPException, Request
+from pydantic import BaseModel
+from sqlalchemy import Engine, select
+
+from satchel.llm.chat import ChatProvider
+from satchel.llm.embeddings import EmbeddingProvider
+from satchel.mcp.auth import ROLE_RANK, authenticate_bearer
+from satchel.oauth import sessions
+from satchel.settings import Settings
+from satchel.store.db import admin_session
+from satchel.store.models import AppUser, Workspace
+
+
+@dataclass
+class ApiContext:
+    engine: Engine
+    embedder: EmbeddingProvider
+    settings: Settings
+    chat: ChatProvider | None = None  # overrides the configured chat provider (tests)
+
+
+class Caller(BaseModel):
+    workspace_id: uuid.UUID
+    user_id: uuid.UUID | None
+    role: str | None = None
+    csrf: str | None = None  # only for cookie sessions
+    auth: str = "dev"  # bearer | cookie | dev
+
+    @property
+    def effective_role(self) -> str:
+        """Dev-header calls without a user act as the lowest role."""
+        return self.role if self.role in ROLE_RANK else "explorer"
+
+    def has_role(self, minimum: str) -> bool:
+        return ROLE_RANK[self.effective_role] >= ROLE_RANK[minimum]
+
+
+def _unauth(detail: str) -> HTTPException:
+    return HTTPException(401, detail, headers={"WWW-Authenticate": 'Bearer realm="satchel"'})
+
+
+class Auth:
+    def __init__(self, ctx: ApiContext) -> None:
+        self.ctx = ctx
+
+    def caller(
+        self,
+        request: Request,
+        authorization: Annotated[str | None, Header()] = None,
+        x_satchel_workspace: Annotated[str | None, Header()] = None,
+        x_satchel_user: Annotated[str | None, Header()] = None,
+    ) -> Caller:
+        eng, st = self.ctx.engine, self.ctx.settings
+        if authorization:
+            p = authenticate_bearer(authorization, engine=eng, settings=st)
+            if p is None:
+                raise _unauth("invalid, expired or revoked token")
+            return Caller(
+                workspace_id=p.workspace_id, user_id=p.user_id, role=p.role, auth="bearer"
+            )
+        cookie = request.cookies.get(sessions.COOKIE)
+        if cookie:
+            info = sessions.load_session(cookie, engine=eng)
+            if info is None:
+                raise _unauth("session expired")
+            if request.method not in sessions.SAFE_METHODS and not sessions.csrf_ok(
+                info, request.headers.get(sessions.CSRF_HEADER)
+            ):
+                raise HTTPException(403, "missing or invalid X-CSRF-Token")
+            return Caller(
+                workspace_id=info.workspace_id, user_id=info.user_id, role=info.role,
+                csrf=info.csrf, auth="cookie",
+            )
+        if not st.dev_auth:
+            raise _unauth("authentication required")
+        # DEV-ONLY header auth (SATCHEL_DEV_AUTH=1): unverified. Without headers (e.g. a UI build
+        # without VITE_DEV_AUTH) it acts as the first admin of the configured workspace
+        # (SATCHEL_WORKSPACE / config file), so `SATCHEL_DEV_AUTH=1 satchel up` works with any UI
+        # build.
+        slug = x_satchel_workspace or st.workspace
+        if not slug:
+            raise HTTPException(401, "dev auth: send X-Satchel-Workspace or set SATCHEL_WORKSPACE")
+        with admin_session(engine=eng) as s:
+            ws = s.scalars(select(Workspace).where(Workspace.slug == slug)).first()
+            if ws is None:
+                raise HTTPException(404, f"unknown workspace: {slug}")
+            if not x_satchel_user and not x_satchel_workspace:
+                admin = s.scalars(
+                    select(AppUser)
+                    .where(AppUser.workspace_id == ws.id, AppUser.role == "admin")
+                    .order_by(AppUser.created_at)
+                ).first()
+                if admin is not None:
+                    return Caller(workspace_id=ws.id, user_id=admin.id, role="admin", auth="dev")
+            user_id: uuid.UUID | None = None
+            role: str | None = None
+            if x_satchel_user:
+                try:
+                    user_id = uuid.UUID(x_satchel_user)
+                except ValueError:
+                    raise HTTPException(400, "X-Satchel-User must be a UUID") from None
+                u = s.scalars(
+                    select(AppUser).where(AppUser.id == user_id, AppUser.workspace_id == ws.id)
+                ).first()
+                if u is None:
+                    raise HTTPException(403, "user is not a member of this workspace")
+                role = u.role
+            return Caller(workspace_id=ws.id, user_id=user_id, role=role, auth="dev")
+
+    def require(self, minimum: str) -> Callable[..., Caller]:
+        """Dependency: an authenticated caller with at least ``minimum`` role."""
+
+        def dep(who: Annotated[Caller, Depends(self.caller)]) -> Caller:
+            if not who.has_role(minimum):
+                raise HTTPException(
+                    403, f"requires the {minimum} role; your role is {who.effective_role}"
+                )
+            return who
+
+        return dep

satchel/api/catalog.py

@@ -0,0 +1,200 @@
+"""Catalog: connections and the asset tree with documentation / endorsement state."""
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import ColumnElement, exists, func, or_, select
+from sqlalchemy.orm import Session
+
+from satchel.api.auth import Auth, Caller
+from satchel.api.common import escape_like
+from satchel.api.connections import secret_source
+from satchel.api.schemas import (
+    AssetDetail,
+    AssetLinkedItem,
+    AssetNode,
+    AssetPage,
+    ConnectionOut,
+    DocRefOut,
+)
+from satchel.core.item_types import yaml_item_dict
+from satchel.sources.precedence import DocRef, group_by_key, load_sources
+from satchel.store.db import workspace_session
+from satchel.store.models import (
+    Asset,
+    Connection,
+    ContextEntityLink,
+    ContextItem,
+    ContextVersion,
+)
+
+
+class _Docs:
+    """Documentation and endorsement lookups from the *published* context.
+
+    When several sources (or a hand-written doc) describe one asset, the primary doc is used
+    (see ``satchel.sources.precedence``) and the others are listed as ``also_described_by``."""
+
+    def __init__(self, s: Session) -> None:
+        self.doc: dict[uuid.UUID, tuple[str, bool]] = {}
+        self.refs: dict[uuid.UUID, tuple[DocRef, list[DocRef]]] = {}
+        groups = group_by_key(
+            ((asset_id, item, ver) for asset_id, item, ver in s.execute(
+                select(ContextEntityLink.asset_id, ContextItem, ContextVersion)
+                .join(ContextVersion, ContextVersion.id == ContextEntityLink.version_id)
+                .join(ContextItem, ContextItem.published_version_id == ContextVersion.id)
+                .where(
+                    ContextItem.type == "asset_doc",
+                    ContextEntityLink.relation == "defines",
+                    ContextItem.state != "deprecated",
+                )
+            )),
+            load_sources(s),
+        )
+        for asset_id, g in groups.items():
+            prim = g.primary
+            self.doc[asset_id] = (
+                prim.item.key, bool(prim.version.meta.get("endorsed")) if prim.version else False
+            )
+            self.refs[asset_id] = (prim.ref, [m.ref for m in g.others])
+        self.endorse: dict[str, tuple[bool, bool]] = {}
+        for meta, body in s.execute(
+            select(ContextVersion.meta, ContextVersion.body)
+            .join(ContextItem, ContextItem.published_version_id == ContextVersion.id)
+            .where(ContextItem.type == "endorsement", ContextItem.state != "deprecated")
+        ):
+            d = yaml_item_dict("endorsement", body, meta)
+            if d.get("asset"):
+                self.endorse[str(d["asset"]).lower()] = (
+                    bool(d.get("endorsed")), bool(d.get("excluded_from_ai")),
+                )
+
+    def node(self, a: Asset, conn_name: str | None) -> AssetNode:
+        doc = self.doc.get(a.id)
+        e_flag, excluded = self.endorse.get(a.fqn.lower(), (False, False))
+        prim, others = self.refs.get(a.id, (None, []))
+        return AssetNode(
+            id=a.id, connection=conn_name, kind=a.kind, fqn=a.fqn, name=a.fqn.split(".")[-1],
+            data_type=a.data_type, dropped=a.dropped_at is not None, has_doc=doc is not None,
+            doc_item_key=doc[0] if doc else None, endorsed=bool(doc and doc[1]) or e_flag,
+            excluded_from_ai=excluded,
+            primary=DocRefOut(source=prim.label, key=prim.key, primary=True) if prim else None,
+            also_described_by=[DocRefOut(source=o.label, key=o.key) for o in others],
+        )
+
+
+def _tree(s: Session, roots: list[Asset], conn_names: dict[uuid.UUID, str]) -> list[AssetNode]:
+    docs = _Docs(s)
+    nodes: dict[uuid.UUID, AssetNode] = {}
+    level = roots
+    out = [docs.node(a, conn_names.get(a.connection_id) if a.connection_id else None)
+           for a in roots]
+    for a, n in zip(roots, out, strict=True):
+        nodes[a.id] = n
+    for _ in range(5):  # database > schema > table > column
+        if not level:
+            break
+        kids = list(
+            s.scalars(
+                select(Asset).where(Asset.parent_id.in_([a.id for a in level])).order_by(Asset.fqn)
+            )
+        )
+        for k in kids:
+            node = docs.node(k, conn_names.get(k.connection_id) if k.connection_id else None)
+            nodes[k.id] = node
+            if k.parent_id in nodes:
+                nodes[k.parent_id].children.append(node)
+        level = kids
+    return out
+
+
+def make_router(auth: Auth) -> APIRouter:
+    r = APIRouter(tags=["catalog"])
+    Any_ = Annotated[Caller, Depends(auth.require("explorer"))]
+    eng = auth.ctx.engine
+
+    @r.get("/v1/connections", response_model=list[ConnectionOut])
+    def list_connections(who: Any_) -> list[ConnectionOut]:
+        with workspace_session(who.workspace_id, who.user_id, engine=eng) as s:
+            n = (
+                select(func.count())
+                .where(Asset.connection_id == Connection.id, Asset.dropped_at.is_(None))
+                .scalar_subquery()
+            )
+            return [
+                ConnectionOut(
+                    id=c.id, name=c.name, kind=c.kind, default_for_ai=c.default_for_ai,
+                    has_secret=c.secret_ref is not None, asset_count=cnt,
+                    secret=secret_source(c.secret_ref),
+                    config=dict(c.config or {}) if who.has_role("admin") else None,
+                )
+                for c, cnt in s.execute(select(Connection, n).order_by(Connection.name))
+            ]
+
+    @r.get("/v1/assets", response_model=AssetPage)
+    def list_assets(
+        who: Any_,
+        connection: Annotated[str | None, Query(description="Connection name")] = None,
+        q: Annotated[str | None, Query(description="Substring of an asset name")] = None,
+        limit: Annotated[int, Query(ge=1, le=500)] = 100,
+        offset: Annotated[int, Query(ge=0)] = 0,
+    ) -> AssetPage:
+        with workspace_session(who.workspace_id, who.user_id, engine=eng) as s:
+            conn_names = {c.id: c.name for c in s.scalars(select(Connection))}
+            conds: list[ColumnElement[bool]] = [Asset.parent_id.is_(None)]
+            if connection:
+                cid = next((i for i, n in conn_names.items() if n == connection), None)
+                if cid is None:
+                    raise HTTPException(404, f"no such connection: {connection}")
+                conds.append(Asset.connection_id == cid)
+            if q and q.strip():
+                pat = f"%{escape_like(q.strip())}%"
+                child = Asset.__table__.alias("child")
+                conds.append(
+                    or_(
+                        Asset.fqn.ilike(pat, escape="\\"),
+                        exists().where(child.c.parent_id == Asset.id,
+                                       child.c.fqn.ilike(pat, escape="\\")),
+                    )
+                )
+            total = s.scalar(select(func.count()).select_from(Asset).where(*conds)) or 0
+            roots = list(
+                s.scalars(
+                    select(Asset).where(*conds).order_by(Asset.fqn).limit(limit).offset(offset)
+                )
+            )
+            return AssetPage(total=total, limit=limit, offset=offset,
+                             assets=_tree(s, roots, conn_names))
+
+    @r.get("/v1/assets/{asset_id}", response_model=AssetDetail)
+    def get_asset(asset_id: uuid.UUID, who: Any_) -> AssetDetail:
+        with workspace_session(who.workspace_id, who.user_id, engine=eng) as s:
+            a = s.get(Asset, asset_id)
+            if a is None:
+                raise HTTPException(404, "no such asset")
+            conn_names = {c.id: c.name for c in s.scalars(select(Connection))}
+            node = _tree(s, [a], conn_names)[0]
+            linked = s.execute(
+                select(ContextItem.key, ContextItem.type, ContextItem.state,
+                       ContextEntityLink.relation)
+                .join(ContextVersion, ContextVersion.item_id == ContextItem.id)
+                .join(ContextEntityLink, ContextEntityLink.version_id == ContextVersion.id)
+                .where(
+                    ContextEntityLink.asset_id == asset_id,
+                    or_(
+                        ContextVersion.id == ContextItem.published_version_id,
+                        ContextVersion.id == ContextItem.current_version_id,
+                    ),
+                )
+                .distinct()
+                .order_by(ContextItem.key, ContextEntityLink.relation)
+            )
+            return AssetDetail(
+                **node.model_dump(), stats=a.stats, first_seen_at=a.first_seen_at,
+                last_seen_at=a.last_seen_at,
+                linked_items=[AssetLinkedItem(key=k, type=t, state=st, relation=rel)
+                              for k, t, st, rel in linked],
+            )
+
+    return r