Skip to content

World's first open-source enterprise world model.

A token reads the entities, history and fact evidence of the bases it reaches, so a service mirroring into Utopia can read its own base back without a person's session (#1263)

Szabo Bogdan68cb3ff70714
diff --git a/crates/utopia-server/src/api/documents_routes.rs b/crates/utopia-server/src/api/documents_routes.rs
index da196cc5..0d184dea 100644
--- a/crates/utopia-server/src/api/documents_routes.rs
+++ b/crates/utopia-server/src/api/documents_routes.rs
@@ -81,7 +81,7 @@ fn content_headers(
Ok(headers)
}
-async fn require_reader_kb(
+pub(crate) async fn require_reader_kb(
state: &AppState,
reader: &SessionOrToken,
kb_id: Uuid,
diff --git a/crates/utopia-server/src/api/graph_routes.rs b/crates/utopia-server/src/api/graph_routes.rs
index 728c51f0..3116474a 100644
--- a/crates/utopia-server/src/api/graph_routes.rs
+++ b/crates/utopia-server/src/api/graph_routes.rs
@@ -6,7 +6,8 @@ use utopia_core::models::Role;
use utopia_core::AppError;
use uuid::Uuid;
-use crate::auth::AuthUser;
+use super::documents_routes::require_reader_kb;
+use crate::auth::{AuthUser, SessionOrToken};
use crate::error::ApiResult;
use crate::state::AppState;
@@ -138,11 +139,11 @@ pub struct EntitySearchQuery {
pub async fn search_entities(
State(state): State<AppState>,
- AuthUser(user): AuthUser,
+ reader: SessionOrToken,
Path(kb_id): Path<Uuid>,
Query(query): Query<EntitySearchQuery>,
) -> ApiResult<Json<serde_json::Value>> {
- require_kb(&state, &user, kb_id, Role::Viewer).await?;
+ require_reader_kb(&state, &reader, kb_id).await?;
// 先校验时刻:一个写错的 `as_of` 配空查询也该回 400,而不是看起来成功
let as_of = parse_instant("as_of", query.as_of.as_deref())?;
if query.q.trim().is_empty() {
@@ -171,11 +172,11 @@ pub struct EntityDetailQuery {
pub async fn entity_detail(
State(state): State<AppState>,
- AuthUser(user): AuthUser,
+ reader: SessionOrToken,
Path((kb_id, entity_id)): Path<(Uuid, Uuid)>,
Query(q): Query<EntityDetailQuery>,
) -> ApiResult<Json<serde_json::Value>> {
- require_kb(&state, &user, kb_id, Role::Viewer).await?;
+ require_reader_kb(&state, &reader, kb_id).await?;
let as_of = parse_instant("as_of", q.as_of.as_deref())?;
// 世界轴不过滤(at = None):面板要的是整条时间线,「此刻成立」那一档由前端
// 按 holds_from / holds_to 分出来(0022)
@@ -518,10 +519,10 @@ pub async fn update_fact_time(
pub async fn fact_evidence(
State(state): State<AppState>,
- AuthUser(user): AuthUser,
+ reader: SessionOrToken,
Path((kb_id, fact_id)): Path<(Uuid, Uuid)>,
) -> ApiResult<Json<serde_json::Value>> {
- require_kb(&state, &user, kb_id, Role::Viewer).await?;
+ require_reader_kb(&state, &reader, kb_id).await?;
let evidence = utopia_store::graph::fact_evidence(&state.pool, kb_id, fact_id).await?;
Ok(Json(json!({ "evidence": evidence })))
}
@@ -626,11 +627,11 @@ fn default_history_per() -> i64 {
/// 与 entity_detail(有效时间轴,只看现行)互补。
pub async fn entity_history(
State(state): State<AppState>,
- AuthUser(user): AuthUser,
+ reader: SessionOrToken,
Path((kb_id, entity_id)): Path<(Uuid, Uuid)>,
Query(q): Query<HistoryQuery>,
) -> ApiResult<Json<serde_json::Value>> {
- require_kb(&state, &user, kb_id, Role::Viewer).await?;
+ require_reader_kb(&state, &reader, kb_id).await?;
let per = q.per.clamp(1, 200);
let page = q.page.max(0);
let (events, total) =
diff --git a/crates/utopia-server/src/api/mod.rs b/crates/utopia-server/src/api/mod.rs
index f0773a6c..ec25e1fe 100644
--- a/crates/utopia-server/src/api/mod.rs
+++ b/crates/utopia-server/src/api/mod.rs
@@ -661,5 +661,8 @@ mod oidc_exchange_tests;
#[cfg(test)]
mod token_setup_tests;
+#[cfg(test)]
+mod token_read_tests;
+
#[cfg(test)]
mod rule_expression_tests;
diff --git a/crates/utopia-server/src/api/token_read_tests.rs b/crates/utopia-server/src/api/token_read_tests.rs
new file mode 100644
index 00000000..1855c84f
--- /dev/null
+++ b/crates/utopia-server/src/api/token_read_tests.rs
@@ -0,0 +1,146 @@
+//! 个人令牌读实体(0014 决定 7):搜实体、实体详情、认知历史、事实证据四条读路由
+//! 收任何一枚活着的令牌。角色照旧是上限,`kb_ids` 排除了的库答 404;改实体仍只认会话。
+use crate::state::AppState;
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use std::sync::Arc;
+use tower::ServiceExt;
+use uuid::Uuid;
+
+struct Fixture {
+ pool: sqlx::PgPool,
+ app: axum::Router,
+ org: Uuid,
+ kb: Uuid,
+ /// 令牌够不着的另一个库
+ other_kb: Uuid,
+ reader: Uuid,
+ entity: Uuid,
+ fact: Uuid,
+ _dir: tempfile::TempDir,
+}
+
+impl Fixture {
+ async fn new() -> anyhow::Result<Option<Self>> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(None);
+ };
+ let pool = sqlx::PgPool::connect(&url).await?;
+ utopia_store::db::migrate(&pool).await?;
+ let id = Uuid::now_v7;
+ let (org, ws, reader, kb, other_kb) = (id(), id(), id(), id(), id());
+ let (person, knows, entity, peer, fact) = (id(), id(), id(), id(), id());
+ // 插进去的只有本地生成的 UUID 和写死的日期
+ sqlx::raw_sql(&format!(
+ "INSERT INTO organizations(id,name) VALUES ('{org}','token-read-test');
+ INSERT INTO workspaces(id,org_id,name) VALUES ('{ws}','{org}','token-read-test');
+ INSERT INTO users(id,org_id,email,display_name,password_hash) VALUES
+ ('{reader}','{org}','{reader}@token-read.test','Reader','unused');
+ INSERT INTO knowledge_bases(id,workspace_id,name) VALUES
+ ('{kb}','{ws}','mirror'), ('{other_kb}','{ws}','other');
+ INSERT INTO kb_members(kb_id,user_id,role) VALUES
+ ('{kb}','{reader}','viewer'), ('{other_kb}','{reader}','viewer');
+ INSERT INTO entity_types(id,kb_id,key,label) VALUES ('{person}','{kb}','person','Person');
+ INSERT INTO relation_types(id,kb_id,key,label,temporal) VALUES
+ ('{knows}','{kb}','knows','knows','state');
+ INSERT INTO entities(id,kb_id,type_id,canonical_name,created_at) VALUES
+ ('{entity}','{kb}','{person}','Zhang San','2026-01-01'),
+ ('{peer}','{kb}','{person}','Li Si','2026-01-01');
+ INSERT INTO facts(id,kb_id,subject_id,predicate_id,object_id,recorded_at,confidence)
+ VALUES ('{fact}','{kb}','{entity}','{knows}','{peer}','2026-01-01',0.9);"
+ ))
+ .execute(&pool)
+ .await?;
+ let dir = tempfile::tempdir()?;
+ let cfg = utopia_core::config::AppConfig {
+ data_dir: dir.path().to_string_lossy().into_owned(),
+ ..Default::default()
+ };
+ let search = Arc::new(utopia_search::SearchIndex::open(
+ &dir.path().join("search"),
+ )?);
+ let state = AppState::new(pool.clone(), &cfg, search, "test-only".into());
+ let app = super::router(state, &cfg);
+ Ok(Some(Self {
+ pool,
+ app,
+ org,
+ kb,
+ other_kb,
+ reader,
+ entity,
+ fact,
+ _dir: dir,
+ }))
+ }
+
+ async fn read_token(&self, kb: Uuid) -> String {
+ utopia_store::tokens::issue(&self.pool, self.reader, "ci", "read", Some(&[kb]), None)
+ .await
+ .expect("issuing a token")
+ .1
+ }
+
+ fn read_paths(&self) -> [String; 4] {
+ 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"),
+ ]
+ }
+
+ async fn get(&self, path: &str, token: &str) -> anyhow::Result<StatusCode> {
+ let request = Request::builder()
+ .uri(format!("/api/v1{path}"))
+ .header("authorization", format!("Bearer {token}"))
+ .body(Body::empty())?;
+ Ok(self.app.clone().oneshot(request).await?.status())
+ }
+
+ async fn cleanup(self) -> anyhow::Result<()> {
+ sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(self.org)
+ .execute(&self.pool)
+ .await?;
+ Ok(())
+ }
+}
+
+#[tokio::test]
+async fn a_read_token_of_a_base_viewer_reads_its_entities_facts_and_history() -> anyhow::Result<()>
+{
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ let result = async {
+ let token = f.read_token(f.kb).await;
+ for path in f.read_paths() {
+ let status = f.get(&path, &token).await?;
+ anyhow::ensure!(status == StatusCode::OK, "{path}: {status}");
+ }
+ Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ result
+}
+
+#[tokio::test]
+async fn a_token_limited_to_another_base_gets_404_on_every_entity_read() -> anyhow::Result<()> {
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ let result = async {
+ let token = f.read_token(f.other_kb).await;
+ for path in f.read_paths() {
+ let status = f.get(&path, &token).await?;
+ anyhow::ensure!(status == StatusCode::NOT_FOUND, "{path}: {status}");
+ }
+ Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ result
+}
diff --git a/crates/utopia-server/src/auth.rs b/crates/utopia-server/src/auth.rs
index 49ebf01c..5a788986 100644
--- a/crates/utopia-server/src/auth.rs
+++ b/crates/utopia-server/src/auth.rs
@@ -176,7 +176,7 @@ impl FromRequestParts<AppState> for AuthUser {
///
/// **不替换 `AuthUser`。** `AuthUser` 把每个 Bearer 都当 JWT 解,令牌在那几百条
/// 路由上一律是 401——那是有意的:哪条路由准令牌进来,要在 0014 里说出理由。
-/// 用这个提取器的只有文档原件(0052)和「把一个库搭起来」那几条。
+/// 用这个提取器的只有文档原件(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 ed3082ae..58cff255 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
@@ -1,6 +1,6 @@
# 0014 · Identity from the person, scope from the token
-- **Status**: Implemented · 2026-10-15 · #180, #318, #1243 · open: tokens across workspaces
+- **Status**: Implemented · 2026-10-16 · #180, #318, #1243 · open: tokens across workspaces
- **Written**: 2026-09-01 · condensed into English 2026-09-03
- **Related**: migration `0014_data_source_grants` gave data sources a grant layer; this is the same question where a machine knocks. [0004](0004-language-and-localization.md) has the server speak English only, MCP error codes included. [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) removes the main objection to opening `remember` over MCP.
@@ -85,6 +85,17 @@ push documents in.
Not done: rotating or deleting a source, changing a base's settings or members, and every
other write still take a session. A token does not create workspaces or tokens.
+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
+ 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.
+
## Dead ends
- **Base-level machine tokens**, one per base and unrelated to a person. It would be a third
@@ -109,6 +120,8 @@ push documents in.
- 2026-10-16: decision 6 let a token create only `statements` sources, though an `api` source is
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.
## Open questions
diff --git a/docs/design/access-and-audit.md b/docs/design/access-and-audit.md
index cc331f69..70770528 100644
--- a/docs/design/access-and-audit.md
+++ b/docs/design/access-and-audit.md
@@ -19,8 +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 and document content take `SessionOrToken`; apart from MCP, every
-other route is session-only [0014 d6]. `ingest_token` on a source is a different kind: plaintext, push-only [0014].
+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].
**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