A write token may set up a base

[gedaiu]

Closes #1243.

What happened

A backend that mirrors many repositories into Utopia needs a base and a statements source per repository. The push is the source key's job (0054), but creating the base and the source took a session, so the backend either held someone's seven-day JWT or a person did the setup by hand for every repository.

What changed

Five routes now also take a personal token with write scope, acting as the person who issued it: POST /workspaces/{id}/kbs, POST /kbs/{id}/sources, GET /kbs/{id}/sources/{sid}/token, POST /kbs/{id}/ontology/imports and POST /kbs/{id}/review/alignment/kind-words/{word}. GET /workspaces/{id}/kbs takes any token, so a client can find a base by name before it creates one.

• One extractor, SessionOrToken, resolves either credential to the same User. Only these routes and document content (0052, where DocumentReader was a near-copy of it and is folded in) use it; AuthUser still reads every bearer as a JWT, so every other route stays session-only.
• The token only narrows. Each handler calls require_write first and then the role check it already had: a read token is refused with 403 token_read_only, a token limited by kb_ids reaches only those bases and creates none (403 token_kb_out_of_scope), and the owner's role is still the ceiling. AppError::CodedForbidden carries those codes, the same shape as CodedConflict, so a client can tell "use another token" from "your role is not enough".
• Expiry and revocation are judged in SQL on every request; a deactivated owner is refused. Audit rows name the owner, as from a session.

0014 gains decision 6 with the reasons it keeps (a living person is the actor, scope from the token, writing must be ticked, no base-level machine tokens or service accounts) and what is not done. Its status line also said can_write was hard-coded false, which #318 had fixed; a dated note corrects it.

Tests

api::token_setup_tests, against a real database: a workspace admin's write token creates a base and a source, reads the push key, passes the import and kind-word checks, and the audit rows name the admin, while an expired and a revoked token from the same person get 401; a read token lists bases and is refused with token_read_only on all five writing routes; a viewer's write token creates no base, and a token limited to base A creates a source in A but not in B and no base, and lists only A.

cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings and cargo test --workspace pass with UTOPIA_TEST_REQUIRE_DB=1 (utopia-server 634 passed, utopia-store 306). The web UI needs no change.

[WaylandYang]

Thank you, this is careful work: the token only narrows, the role checks are unchanged, and the read/expired/revoked/kb_ids cases are all covered by tests that run in CI.

One change before merge: please limit what a token can create in POST /kbs/{id}/sources to the push kinds (statements, and api if you need it), and refuse other kinds from a token with a coded 403. As it stands a write token can create url/rss/custom sources, which the server starts fetching immediately (sources_routes.rs:111), with stored credentials for custom. That turns a leaked CI token from "can read and propose memories" into "can make the server call any address on a schedule", and #1243 only needs the statements source. A session keeps creating every kind. One test case for the refusal is enough.

Also, please put the token id in the audit metadata on the rows these routes already write (source.created, alignment.kind_word_decided, ontology import). 0014 decision 5 relies on knowing which token acted; without it, an admin can't tell what a leaked token did before revoking it. A line in decision 6 noting that a system admin's write token acts as Owner in every base would also help the next reader.

[gedaiu]

Thanks, both done in 0ed8e9b.

• Source kinds: a token now creates only statements sources. Every other kind is refused with a coded 403 token_source_kind after the write check and before anything is written; sessions still create every kind. I left out api: it is also a push kind, but A write-scoped personal token could create a knowledge base and a source in its owner's workspace #1243 only needs statements, so it stays out until someone does. The refusal is tested by a_write_token_creating_a_url_source_is_refused_with_token_source_kind, which checks the 403 and code and that no source row exists.
• Audit: source.created, alignment.kind_word_decided and ontology.imported carry detail.token_id when a token acted, through a small audit::via_token helper. This includes packs installed while creating a base. A session's detail is unchanged. a_live_write_token_of_a_workspace_admin_sets_up_a_base_and_a_dead_one_does_not now asserts the token id on the source.created row.
• 0014 decision 6: it now says that a system admin's write token acts as Owner in every base, that tokens create only statements sources and why, and which audit rows name the token (per decision 5). I removed the old "not done" sentence about audit rows not naming the token. access-and-audit.md now says "a statements source".

Local runs: fmt and clippy (-D warnings) are clean. The utopia-server bin suite passes, except the load-sensitive the_embedding_gate_is_never_held_beyond_its_ceiling, which passes on its own.

[WaylandYang]

Thank you, both points are addressed exactly as asked: a token now creates only statements sources and is refused with token_source_kind before anything is written, sessions are unaffected, and the three audit rows carry detail.token_id so a leaked token's actions can be traced before it is revoked. Decision 6 reads well with the system-admin sentence. Merging.