Page or section
docs/toolhive/guides-registry/authorization.mdx (published at https://docs.stacklok.com/toolhive/guides-registry/authorization), with a follow-on cross-reference needed in configuration.mdx.
What's wrong?
Two related problems.
1. The interaction between the three claim scopes is never documented. The page covers claim containment, default-deny, the publish rules, and a worked example, but never states the division of responsibility, so readers can't build a correct mental model:
- Registry claims gate access to the registry view (403 on the whole
/registry/{name}/... surface if the caller doesn't cover them).
- Entry claims gate per-entry visibility within a registry the caller can already access. A consumer sees an entry only if they cover both the registry's claims and the entry's claims. Source claims never enter this read filter.
- Source claims control admin visibility/management of the source (
/v1/sources) and whether the source can be linked into a registry (registry create/update must cover each linked source's claims). They do not filter entries at read time.
The page also never spells out the synced-vs-managed asymmetry, which is the main source of confusion:
- For synced sources (git/api/file/kubernetes), entries inherit the source's claims during sync, and a config change re-propagates them. So source claim → entry claim → read visibility, indirectly.
- For managed sources, there is no inheritance: each published entry carries its own claims from the publish payload, and the source's claims are irrelevant to both publish and read.
2. The publish framing is inaccurate. In the worked-example walkthrough, the "Writers ... can publish to the shared managed source" bullet says the org: "acme" claim on the source "is what makes it reachable to non-super-admin callers," framed as the reason writers can publish. This implies source claims gate publishing, which they don't. What the source claim actually enables is linking the source into registries (so published entries surface) and admin management of the source, not the ability to publish.
Suggested fix
- Add a "How claims interact" section to
authorization.mdx with the registry / entry / source division above, plus the synced-inherits vs managed-explicit note.
- Correct the publish bullet so it attributes the source claim to registry-linking and management, not to publish permission.
- Add a cross-reference from the managed-source section of
configuration.mdx to the new section.
Additional context
There is a parallel behavioral discrepancy tracked in stacklok/toolhive-registry-server#845 (publishing does not check source claims, contradicting auth.md §4). The wording fix here should align with whatever is decided there.
Page or section
docs/toolhive/guides-registry/authorization.mdx(published at https://docs.stacklok.com/toolhive/guides-registry/authorization), with a follow-on cross-reference needed inconfiguration.mdx.What's wrong?
Two related problems.
1. The interaction between the three claim scopes is never documented. The page covers claim containment, default-deny, the publish rules, and a worked example, but never states the division of responsibility, so readers can't build a correct mental model:
/registry/{name}/...surface if the caller doesn't cover them)./v1/sources) and whether the source can be linked into a registry (registry create/update must cover each linked source's claims). They do not filter entries at read time.The page also never spells out the synced-vs-managed asymmetry, which is the main source of confusion:
2. The publish framing is inaccurate. In the worked-example walkthrough, the "Writers ... can publish to the
sharedmanaged source" bullet says theorg: "acme"claim on the source "is what makes it reachable to non-super-admin callers," framed as the reason writers can publish. This implies source claims gate publishing, which they don't. What the source claim actually enables is linking the source into registries (so published entries surface) and admin management of the source, not the ability to publish.Suggested fix
authorization.mdxwith the registry / entry / source division above, plus the synced-inherits vs managed-explicit note.configuration.mdxto the new section.Additional context
There is a parallel behavioral discrepancy tracked in stacklok/toolhive-registry-server#845 (publishing does not check source claims, contradicting
auth.md §4). The wording fix here should align with whatever is decided there.