World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-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.rsindex 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsindex 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.mdindex 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 everyother 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 ispush-only as well; a backend mirroring several kinds of documents pushes them through one. Atoken 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 questionsdiff --git a/docs/design/access-and-audit.md b/docs/design/access-and-audit.mdindex 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 oncesnippet [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'srole 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