Skip to content

World's first open-source enterprise world model.

A write token creates an api source as well as a statements source, since both are push-only and a backend mirrors code and docs into a base as plain documents (#1274)

Szabo Bogdan92800db074c8
diff --git a/crates/utopia-server/src/api/sources_routes.rs b/crates/utopia-server/src/api/sources_routes.rs
index 52db4125..2c786394 100644
--- a/crates/utopia-server/src/api/sources_routes.rs
+++ b/crates/utopia-server/src/api/sources_routes.rs
@@ -84,11 +84,12 @@ pub struct CreateBody {
pub sync_cron: Option<String>,
}
-/// 写令牌也能建(0014 决定 6):给一个镜像仓库配 `statements` 来源,不该要人
+/// 写令牌也能建(0014 决定 6):给一个镜像仓库配 `statements` 或 `api` 来源,不该要人
/// 一个个手点。
///
-/// 令牌只建 `statements`:`url`/`rss`/`custom` 一建好服务器就按时去拉(`custom`
-/// 还带着存下的凭据),漏出去的 CI 令牌不该能让服务器定时去敲任意地址。会话照旧建什么都行
+/// 令牌只建推送型(`statements`/`api`,服务器不替它们拉任何东西):`url`/`rss`/`custom`
+/// 一建好服务器就按时去拉(`custom` 还带着存下的凭据),漏出去的 CI 令牌不该能让服务器定时去敲
+/// 任意地址。会话照旧建什么都行
pub async fn create(
State(state): State<AppState>,
caller: SessionOrToken,
@@ -96,10 +97,11 @@ pub async fn create(
Json(body): Json<CreateBody>,
) -> ApiResult<Json<serde_json::Value>> {
caller.require_write(Some(kb_id))?;
- if caller.pat.is_some() && body.kind != "statements" {
+ if caller.pat.is_some() && !is_push_kind(&body.kind) {
return Err(utopia_core::AppError::CodedForbidden {
code: "token_source_kind",
- message: "A token creates only statements sources; other kinds take a session".into(),
+ message: "A token creates only statements or api sources; other kinds take a session"
+ .into(),
}
.into());
}
@@ -130,7 +132,7 @@ pub async fn create(
}
// api 来源:生成专属推送密钥(此后可随时经 get_token 查看)
let mut ingest_token: Option<String> = None;
- if has_push_token(&source) {
+ if is_push_kind(&source.kind) {
let token = new_ingest_token();
utopia_store::sources::set_ingest_token(&state.pool, source.id, &token).await?;
ingest_token = Some(token);
@@ -156,8 +158,8 @@ pub async fn create(
/// 有推送密钥的来源:`api` 推文档,`statements` 推陈述(0054)。两种的密钥同一套
/// 生成、查看、轮换
-fn has_push_token(source: &utopia_core::models::Source) -> bool {
- matches!(source.kind.as_str(), "api" | "statements")
+fn is_push_kind(kind: &str) -> bool {
+ matches!(kind, "api" | "statements")
}
/// 查看推送密钥(Editor;列表响应从不携带,查看走这里)。
@@ -171,7 +173,7 @@ pub async fn get_token(
caller.require_write(Some(kb_id))?;
require_kb(&state, &caller.user, kb_id, Role::Editor).await?;
let source = source_in_kb(&state, kb_id, source_id).await?;
- if !has_push_token(&source) {
+ if !is_push_kind(&source.kind) {
return Err(utopia_core::AppError::NotFound.into());
}
Ok(Json(json!({ "ingest_token": source.ingest_token })))
@@ -185,7 +187,7 @@ pub async fn rotate_token(
) -> ApiResult<Json<serde_json::Value>> {
require_kb(&state, &user, kb_id, Role::Editor).await?;
let source = source_in_kb(&state, kb_id, source_id).await?;
- if !has_push_token(&source) {
+ if !is_push_kind(&source.kind) {
return Err(utopia_core::AppError::NotFound.into());
}
let token = new_ingest_token();
diff --git a/crates/utopia-server/src/api/token_setup_tests.rs b/crates/utopia-server/src/api/token_setup_tests.rs
index c1b8da78..bf794868 100644
--- a/crates/utopia-server/src/api/token_setup_tests.rs
+++ b/crates/utopia-server/src/api/token_setup_tests.rs
@@ -296,6 +296,33 @@ async fn a_live_write_token_of_a_workspace_admin_sets_up_a_base_and_a_dead_one_d
result
}
+#[tokio::test]
+async fn a_write_token_creates_an_api_source_and_reads_its_push_key() -> anyhow::Result<()> {
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ let result = async {
+ let kb = f.seeded_kb("docs-mirror").await?;
+ let token = f.token(f.admin, "write", None).await;
+
+ let (status, created) = f.create_source_of_kind(kb, &token, "api").await?;
+ anyhow::ensure!(status == StatusCode::OK, "{status} {created}");
+ let source: Uuid = serde_json::from_value(created["source"]["id"].clone())?;
+
+ let (status, key) = f.push_key(kb, source, &token).await?;
+ anyhow::ensure!(
+ status == StatusCode::OK
+ && key["ingest_token"] == created["ingest_token"]
+ && key["ingest_token"].is_string(),
+ "{status} {key} vs {created}"
+ );
+ anyhow::Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ result
+}
+
#[tokio::test]
async fn a_write_token_creating_a_url_source_is_refused_with_token_source_kind(
) -> anyhow::Result<()> {
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 8c83b864..ed3082ae 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
@@ -70,9 +70,11 @@ push documents in.
it cannot create one, since a base that does not exist yet is in no list
(`token_kb_out_of_scope`); revocation and expiry are judged in SQL on every request. Nothing
here is a base-level machine token or a service account. A token creates only `statements`
- sources: a `url`, `rss` or `custom` source starts the server fetching on a schedule, with
- stored credentials for `custom`, which would turn a leaked CI token into a way to make the
- server call any address; other kinds from a token are refused with `token_source_kind`, and a
+ and `api` sources, both push-only: the server fetches nothing for them and the client pushes
+ with the source key, so a backend mirroring code and docs as plain documents sets up its `api`
+ source the same way. A `url`, `rss` or `custom` source starts the server fetching on a
+ schedule, with stored credentials for `custom`, which would turn a leaked CI token into a way
+ to make the server call any address; other kinds from a token are refused with `token_source_kind`, and a
session still creates every kind. The audit rows these routes write (`source.created`,
`alignment.kind_word_decided`, `ontology.imported`) carry the acting token's id as
`detail.token_id`, so before revoking a leaked token an admin can see what it did (decision
@@ -104,6 +106,9 @@ push documents in.
- 2026-10-15: the status line still said `can_write` was hard-coded false. #318 had already
computed it from the token's scope and the person's role, and `remember` has been reachable
over MCP with a write token since then. The line now names what is open.
+- 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.
## Open questions
diff --git a/docs/design/access-and-audit.md b/docs/design/access-and-audit.md
index 4f83985d..cc331f69 100644
--- a/docs/design/access-and-audit.md
+++ b/docs/design/access-and-audit.md
@@ -16,7 +16,7 @@ SHA-256 hash, `scope` read or write, `kb_ids` or every base, `expires_at` with 9
default, `last_used_at`, `revoked_at` as a trace); effective permission is the person's role
intersected with the token's scope; every MCP call re-runs authentication, scope and role in SQL and
writes an audit row `mcp.tool_called`; the tokens page shows the plaintext once beside a client
-snippet [0014]. A `write` token also sets up a base as its owner: creating a base and a `statements` source,
+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