Skip to content

World's first open-source enterprise world model.

A token reads a base's graph overview and neighbourhood (#1264)

Szabo Bogdancd14e9578ae5
diff --git a/crates/utopia-server/src/api/graph_routes.rs b/crates/utopia-server/src/api/graph_routes.rs
index 3116474a..8eb3e165 100644
--- a/crates/utopia-server/src/api/graph_routes.rs
+++ b/crates/utopia-server/src/api/graph_routes.rs
@@ -71,11 +71,11 @@ pub struct OverviewQuery {
pub async fn overview(
State(state): State<AppState>,
- AuthUser(user): AuthUser,
+ reader: SessionOrToken,
Path(kb_id): Path<Uuid>,
Query(q): Query<OverviewQuery>,
) -> ApiResult<Json<serde_json::Value>> {
- require_kb(&state, &user, kb_id, Role::Viewer).await?;
+ require_reader_kb(&state, &reader, kb_id).await?;
let at = parse_instant("at", q.at.as_deref())?;
let as_of = parse_instant("as_of", q.as_of.as_deref())?;
// 画多少个是渲染的事,库里有多少是知识库的事——两个数都回,界面才说得出
@@ -105,11 +105,11 @@ pub struct NeighborhoodQuery {
pub async fn neighborhood(
State(state): State<AppState>,
- AuthUser(user): AuthUser,
+ reader: SessionOrToken,
Path(kb_id): Path<Uuid>,
Query(q): Query<NeighborhoodQuery>,
) -> ApiResult<Json<serde_json::Value>> {
- require_kb(&state, &user, kb_id, Role::Viewer).await?;
+ require_reader_kb(&state, &reader, kb_id).await?;
let at = parse_instant("at", q.at.as_deref())?;
let as_of = parse_instant("as_of", q.as_of.as_deref())?;
let (nodes, edges) = utopia_store::graph::neighborhood(
diff --git a/crates/utopia-server/src/api/token_read_tests.rs b/crates/utopia-server/src/api/token_read_tests.rs
index 1855c84f..b9d52d52 100644
--- a/crates/utopia-server/src/api/token_read_tests.rs
+++ b/crates/utopia-server/src/api/token_read_tests.rs
@@ -1,4 +1,4 @@
-//! 个人令牌读实体(0014 决定 7):搜实体、实体详情、认知历史、事实证据四条读路由
+//! 个人令牌读图(0014 决定 7):搜实体、实体详情、认知历史、事实证据、图总览、邻域六条读路由
//! 收任何一枚活着的令牌。角色照旧是上限,`kb_ids` 排除了的库答 404;改实体仍只认会话。
use crate::state::AppState;
use axum::body::Body;
@@ -81,13 +81,15 @@ impl Fixture {
.1
}
- fn read_paths(&self) -> [String; 4] {
+ fn read_paths(&self) -> [String; 6] {
let (kb, entity, fact) = (self.kb, self.entity, self.fact);
[
format!("/kbs/{kb}/entities?q=Zhang"),
format!("/kbs/{kb}/entities/{entity}"),
format!("/kbs/{kb}/entities/{entity}/history"),
format!("/kbs/{kb}/facts/{fact}/evidence"),
+ format!("/kbs/{kb}/graph/overview"),
+ format!("/kbs/{kb}/graph/neighborhood?entity={entity}"),
]
}
@@ -109,8 +111,7 @@ impl Fixture {
}
#[tokio::test]
-async fn a_read_token_of_a_base_viewer_reads_its_entities_facts_and_history() -> anyhow::Result<()>
-{
+async fn a_read_token_of_a_base_viewer_gets_200_on_every_graph_read() -> anyhow::Result<()> {
let Some(f) = Fixture::new().await? else {
return Ok(());
};
@@ -128,7 +129,7 @@ async fn a_read_token_of_a_base_viewer_reads_its_entities_facts_and_history() ->
}
#[tokio::test]
-async fn a_token_limited_to_another_base_gets_404_on_every_entity_read() -> anyhow::Result<()> {
+async fn a_token_limited_to_another_base_gets_404_on_every_graph_read() -> anyhow::Result<()> {
let Some(f) = Fixture::new().await? else {
return Ok(());
};
diff --git a/crates/utopia-server/src/auth.rs b/crates/utopia-server/src/auth.rs
index 5a788986..f091f4f9 100644
--- a/crates/utopia-server/src/auth.rs
+++ b/crates/utopia-server/src/auth.rs
@@ -176,7 +176,8 @@ impl FromRequestParts<AppState> for AuthUser {
///
/// **不替换 `AuthUser`。** `AuthUser` 把每个 Bearer 都当 JWT 解,令牌在那几百条
/// 路由上一律是 401——那是有意的:哪条路由准令牌进来,要在 0014 里说出理由。
-/// 用这个提取器的只有文档原件(0052)、「把一个库搭起来」那几条和读实体那几条(决定 7)。
+/// 用这个提取器的只有文档原件(0052)、「把一个库搭起来」那几条和读图那几条:搜实体、
+/// 实体详情、认知历史、事实证据、图总览、邻域(决定 7)。
///
/// 令牌只收窄:`pat` 在的时候,路由先问 [`Self::require_write`] 或
/// [`Self::reaches`],角色照旧由 `require_kb` 与工作区角色判。
diff --git a/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
index 58cff255..850e9015 100644
--- a/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
+++ b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
@@ -87,14 +87,18 @@ push documents in.
7. **A token reads the graph** (added 2026-10-16, #1262). A service that mirrors into a base reads the
base back to check what landed, and a session JWT is the wrong credential for a backend
- (decision 6). Four reads now also take any live token, acting as its owner: searching a base's
+ (decision 6). Six reads now also take any live token, acting as its owner: searching a base's
entities (`GET /kbs/{id}/entities`), an entity's detail (`GET /kbs/{id}/entities/{eid}`), its
- record-axis history (`…/history`), and a fact's evidence (`GET /kbs/{id}/facts/{fid}/evidence`).
- Search finds the entity by name; the detail gives its facts, names and derivations; the
- history says when we changed our mind; the evidence ties a fact to its sentence. Read is the
- lowest scope, so any token qualifies; the owner's role is still the ceiling and Viewer
- suffices; a token whose `kb_ids` exclude the base gets 404, as for document content (0052).
- Changing an entity on the same path (`PATCH`) still takes a session.
+ record-axis history (`…/history`), a fact's evidence (`GET /kbs/{id}/facts/{fid}/evidence`),
+ the graph overview (`GET /kbs/{id}/graph/overview`) and an entity's neighbourhood
+ (`GET /kbs/{id}/graph/neighborhood`). Search finds the entity by name; the detail gives its
+ facts, names and derivations; the history says when we changed our mind; the evidence ties a
+ fact to its sentence; the overview gives the most connected entities with the base's totals,
+ so a client sees the shape of what it pushed; the neighbourhood gives the entities around one,
+ so it can follow what a statement touches, and one started from another base's entity comes
+ back empty. Read is the lowest scope, so any token qualifies; the owner's role is still the
+ ceiling and Viewer suffices; a token whose `kb_ids` exclude the base gets 404, as for document
+ content (0052). Changing an entity on the same path (`PATCH`) still takes a session.
## Dead ends
@@ -121,7 +125,8 @@ push documents in.
push-only as well; a backend mirroring several kinds of documents pushes them through one. A
token now creates `api` sources too.
- 2026-10-16: decision 7 opens four graph reads to any token; decision 6's "only these routes
- and document content" now also counts them.
+ and document content" now also counts them. 2026-10-19: the graph overview and neighbourhood
+ join them.
## Open questions
diff --git a/docs/design/access-and-audit.md b/docs/design/access-and-audit.md
index 70770528..86e533c3 100644
--- a/docs/design/access-and-audit.md
+++ b/docs/design/access-and-audit.md
@@ -19,9 +19,9 @@ writes an audit row `mcp.tool_called`; the tokens page shows the plaintext once
snippet [0014]. A `write` token also sets up a base as its owner: creating a base and a `statements` or `api` source,
reading the source's push key, importing an ontology and deciding a kind word, with the owner's
role unchanged as the ceiling; any token lists a workspace's bases; a token limited by `kb_ids`
-creates no base. These routes, document content and four graph reads (entity search, detail,
-history, fact evidence; Viewer suffices, `kb_ids` answers 404) take `SessionOrToken`; apart from
-MCP, every other route is session-only [0014 d6, d7]. `ingest_token` on a source is a different kind: plaintext, push-only [0014].
+creates no base. These routes, document content and six graph reads (entity search, detail,
+history, fact evidence, overview, neighbourhood; Viewer suffices, `kb_ids` answers 404) take
+`SessionOrToken`; apart from MCP, every other route is session-only [0014 d6, d7]. `ingest_token` on a source is a different kind: plaintext, push-only [0014].
**Another app can trade its user's fresh ID token for a session.** `POST /auth/oidc/exchange`
accepts an ID token from the configured issuer whose audience is in