[gedaiu]

Part of #1262.

What happened

A backend that mirrors into a base needs the base's ontology to turn a class key into a type id, and then the members of that class. Both reads took a session JWT, so a personal token got 401.

What changed

GET /kbs/{id}/ontology and GET /kbs/{id}/ontology/entity-types/{type_id}/entities take SessionOrToken and call require_reader_kb (0052): the owner needs Viewer, any token scope may read, and a token whose kb_ids exclude the base gets 404. Neither handler changes what it returns, and the instances read keeps its missing_predicate filter (#1269). The create, update and delete routes on the same paths stay session-only.

Decision 7 in 0014 now counts eight graph reads, with a reason for each new one, and its revision line gains one sentence. The SessionOrToken comment in auth.rs and docs/design/access-and-audit.md name both reads.

Tests

The two GETs join read_paths in api::token_read_tests, so the instances read runs against the fixture's person class with its two members. A viewer's read token gets 200 on every path, and a token limited to another base gets 404. Switching either route back to session-only makes both tests fail with 401.

cargo test -p utopia-server against Postgres with UTOPIA_TEST_REQUIRE_DB=1, cargo fmt --all -- --check and cargo clippy -p utopia-server --all-targets -- -D warnings are clean.

🤖 Generated with Claude Code

[WaylandYang]

Thank you. Both routes are GETs and go through the same require_reader_kb as document content, so the owner's role is the ceiling and a base outside kb_ids is a 404. The store reads underneath are bound to the base in the path: entity_instances filters on kb_id and type_id together, so a class id from another base returns an empty page rather than that base's members, and merged entities stay out. The create, update and delete routes on the same paths stay session-only. Both tests run in CI and fail without the change.

As asked on #1264, the docs need to line up before merge:

1. Please rebase on #1263 (and #1264 once it's in). Then add these two routes, with their reasons, to its decision 7 ("A token reads the graph") instead of adding another decision 7, and extend its revision line rather than adding a new one. One idea should be one decision, so a reader finds every token-readable route in one place.
2. Please add the ontology reads to the SessionOrToken comment in auth.rs (line 179 on dev). That comment is where a reader of the code learns which routes a token can reach.
3. Please take #1262 off the 0014 status line. It goes there with the last of the read PRs, the same as in #1263.

One suggestion while you rebase: token_read_tests from #1263 already has a person type with two entities in the base and a second base for the 404 case. Adding these two GETs there would be about ten lines instead of a fourth copy of the fixture, and the instances check would see a real member rather than total == 0.

[gedaiu]

Thanks. Once #1263 (and #1264) are in I'll rebase this, fold the two ontology reads with their reasons into decision 7 and extend its revision line, add them to the SessionOrToken list in auth.rs, drop #1262 from the status line, and move the two GETs into token_read_tests so the instances check sees a real member instead of a fourth fixture.

[gedaiu]

Moving this to draft so only one of the #1262 reads is open at a time, as you asked there. Once #1263 is in I'll rebase this onto it, fold the routes into decision 7 and the shared token_read_tests fixture as agreed above, and mark it ready again. Thanks.

[gedaiu]

Thank you @WaylandYang, both for the careful review and for the fixture suggestion, which made this a lot smaller. I've rebased onto dev and handled each point:

1. Both ontology reads are now in decision 7 ("A token reads the graph"), which counts eight reads with a reason for each. I extended the existing revision line by one sentence and added no new decision.
2. The SessionOrToken comment in auth.rs lists the ontology and a class's instances, and access-and-audit.md names them too.
3. A personal token could read the graph of the bases it reaches #1262 is not on the 0014 status line, so it stays off until the last of the reads.

On the suggestion: the two GETs now sit in read_paths in token_read_tests, and the separate test file is gone. The instances check now sees a real member of the person class.

It is ready for another look whenever suits you.

[gedaiu]

A gentle ping whenever you have a moment, no rush. This is rebased on dev with the 0014 route list updated, which were the two things you mentioned on #1262. Thank you!

[WaylandYang]

Rebased onto dev with #1263/#1264, and the two reads sit in 0014 decision 7's single list with their reasons. Approving; this supersedes the 10-16 change request.