# KB / KB Source AGS Permission Matrix > Canonical path: `specs/kb/kb-ags-permission-matrix.md` > Status: living architecture matrix > Scope: Knowledge Base, KB source, and AGS repository / wiki / access-ledger permission mapping. This matrix defines how AgentTeam and MeshX Knowledge Base resources map to AGS resources and which authorization facts are required before humans or agents receive product or repository access. ## 1. Resources and AGS mapping | AgentTeam / MeshX resource | MeshX source of truth | AGS / repository resource | Visibility and purpose | Authorization source | | -------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Knowledge Base | `knowledge_bases` + `knowledge_base_grants` | No standalone AGS repository; KB is a MeshX control-plane resource | Workspace-public metadata and retrieval surface | Workspace-member default role may be `view` / `edit` / `manage`; organization and workspace owners/admins implicitly receive KB `manage`; the KB-level repository access default may be `none` / `read` / `write` / `manage`; explicit human grant may be `owner` / `manage` / `edit` / `view` / `none`; agent grant role is `view` with read/write repository profile | | KB source (canonical mode) | `knowledge_base_sources` + `resource_repositories(resource_type=kb_source, repo_role=canonical)` | `/` AGS repository | User-visible source repository | Source creator access is recorded as durable repository access intent and reconciled; explicit KB human grant may materialize repository access from KB default or repository-row override | | KB source (mirror mode) | `knowledge_base_sources` + `source_mirrors` + `resource_repositories(repo_role=mirror)` | `/` AGS repository | User-visible mirrored repository | Same as canonical; mirror credential lookup is scoped to the mirror repository | | KB insights | `resource_repositories(repo_role=insights)` | `/.kb` AGS repository and wiki pages | System-managed analysis / knowledge store; not human-exposed by default | Source and insights access are independently configurable by repository role; agent KB grants may materialize read access to insights when retrieval requires it; human access to insights requires explicit repository intent | | Repository access product intent | `knowledge_base_grants.repository_access_profile` + repository-row override table | No direct AGS resource | KB-owned source of truth for desired human repository access | Updated only by KB `owner` / `manage` actors | | Repository access ledger | `resource_repository_access_grants` | AGS collaborators for source repositories | Audit, reconciliation, and safe revoke ledger | Created from KB grant intent and effective profile; revoke only removes MeshX-owned materialization | ## 2. Human KB role matrix The “workspace member without explicit grant” column follows the KB's current all-workspace-members default role, which is always at least `view`. An explicit `none` grant denies inherited workspace-member access. Active organization and workspace owners/admins are a separate authority: they implicitly resolve to KB `manage`, including over an explicit `none`, but receive no implied AGS repository access. | Operation | Workspace member without explicit grant | Explicit `none` | `view` | `edit` | `manage` | `owner` | | ------------------------------------------- | ------------------------------------------- | --------------- | ----------- | ----------- | ----------- | ----------- | | List / open KB metadata | Yes | No | Yes | Yes | Yes | Yes | | Retrieval / read through MeshX product APIs | Yes | No | Yes | Yes | Yes | Yes | | List source metadata | Yes | No | Yes | Yes | Yes | Yes | | Create / update source | Yes only when default is `edit` or `manage` | No | No | Yes | Yes | Yes | | Delete source | Yes only when default is `manage` | No | No | No | Yes | Yes | | List / mutate KB permissions | Yes only when default is `manage` | No | No | No | Yes | Yes | | Grant AGS repository access profile | Yes only when default is `manage` | No | No | No | Yes | Yes | | Set repository-row override | Yes only when default is `manage` | No | No | No | Yes | Yes | | Import / overwrite source UA Dashboard | Yes only when default is `edit` or `manage` and caller is workspace owner/admin | No | No | Yes only for workspace owner/admin | Yes only for workspace owner/admin | Yes only for workspace owner/admin | | Read source UA Dashboard | Yes | No | Yes | Yes | Yes | Yes | | Direct AGS repository read/write/admin | Not implied | Not implied | Not implied | Not implied | Not implied | Not implied | ## 3. Human repository access matrix Human repository access is independent from the KB product role. The KB-level repository access default is stored on the knowledge base and is used when a human grant or repository row inherits repository access. Repository access is materialized only for explicit KB grants that carry a repository access intent. The configured repository row is identified by `(source_id, repo_role)`, so the user-visible source repository and the system-managed `insights` repository can be granted, denied, or repaired independently. Effective repository access is resolved by the precedence model in [`kb-repository-access-grants.md`](./kb-repository-access-grants.md): KB-level default, workspace profile, explicit repository-row override, then agent binding/grant policy for agent materialization. | Effective profile | AGS collaborator permission | Repository capability | KB capability implied | | ----------------- | --------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------- | | `none` | none from this KB intent | No KB-owned AGS collaborator access for that repository row | None | | `read` | `read` | Browse repository-backed source surfaces that require AGS read | None beyond the separately authorized KB role | | `write` | `write` | Maintain repository-backed source content and work items that require AGS write | None beyond the separately authorized KB role | | `manage` | `admin` | Manage AGS repository settings-like operations exposed by the source surface | None beyond the separately authorized KB role | A subject with repository `read`, `write`, or `manage` still needs KB visibility before MeshX product APIs or KB source detail routes expose KB data. A subject with KB `manage` still needs an effective repository profile before AGS-backed source tabs work against a private repository. ## 4. Agent KB access matrix | Path | Required subject proof | Required KB proof | AGS materialization | Authorization invariant | | ---------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `GET /api/v1/workspaces/:workspaceId/kb/agents/{agent_id}/accessible` | Authenticated user must own or control `agent_id` through trusted AgentTeam-forwarder agent claims | Existing `knowledge_base_grants(subject_type=agent, role=view)` | None during read | Fail closed when owned-agent proof is absent or stale | | `PUT /api/v1/workspaces/:workspaceId/kb/agents/{agent_id}/permissions` | Same owned-agent proof | Acting user must be able to view each requested KB; requested write access requires equivalent human edit/manage or write repository capability | Adds/removes agent KB grants and reconciles selected read/write access to eligible source repositories | Check target-agent ownership and prevent repository-access escalation before mutating grants | | KB permission grant with `subjectType=agent` | Same owned-agent proof for target `subjectId` | Acting user must manage the KB | Agent grant reconciles read collaborator rows for eligible source repositories | Check target-agent ownership through the KB-centric grant surface | | Agent retrieval / citations | Agent id is selected by retrieval request or agent-thread attestation | Selected KBs must be present in agent KB grants | Uses source repository / wiki readers through MeshX product APIs | Runtime retrieval is authorized by agent KB grant intersection, not by human grant-editor ownership | ## 5. AGS repository materialization rules - Source creation provisions exactly one user-visible repository (`canonical` or `mirror`) plus one system-managed `insights` repository. - KB-created source repositories are private AGS repositories. The KB source creation API must not accept client-selected public/private visibility; users receive direct repository access only through explicit KB repository-access intent or another independent AGS authorization path. - Human repository access profiles (`none`, `read`, `write`, `manage`) apply per mapped repository role. `insights` remains closed by default, but an explicit KB-owned repository intent may grant it without granting the user-visible source repository, and the reverse is also valid. - Human repository-row overrides take precedence over the KB-level repository access default for that explicit grant, source, and repository role. - The all-workspace-members KB default does not materialize AGS repository access for every workspace member. - Agent KB grants carry a read/write repository profile and reconcile that selected access level to the independently configured source and/or `insights` repositories that retrieval or agent-authored maintenance requires. Legacy/empty agent repository profiles fall back to read. Opening insights access never implies opening the user-visible source repository, and source access never implies insights access. - Revocation is scoped by `resource_repository_access_grants.intent_type=kb_grant` and intent id; it must not remove stronger or independent materialized access from another MeshX intent. - Blocked AGS grant/revoke operations keep the product grant and mark repository access blocked; deletion/removal fails closed until repair. - Permission rank for reconciliation is `none` < `read` < `write` < `admin`; KB repository profile `manage` maps to AGS `admin`. ## 6. Workspace and forwarder boundaries - KB product routes must run behind the same current-workspace forwarder gate as Memory and Skills, so forwarded MeshX requests receive a workspace id derived from AgentTeam current-workspace authorization instead of treating a raw client header as proof of membership. - Forwarded KB requests carry `workspace_ids` in the trusted JWT. - Forwarded KB agent-control routes (`/api/v1/workspaces/:workspaceId/kb/agents/...` and KB permissions routes) also carry `owned_agent_ids` / `owned_agents` claims for MeshX owned-agent checks. - MeshX direct/internal callers without an agent ownership source or trusted owned-agent claims fail closed for agent-centric KB reads and grant mutations. ## 7. Required security controls 1. **KB workspace boundary**: Browser-facing KB control-plane routes must validate the selected workspace through AgentTeam before proxying to MeshX. MeshX must not treat `X-Workspace-Id` from an untrusted client as independent workspace-membership proof. 2. **KB agent access write-side escalation guard**: `GrantAgentKnowledgeBaseAccess`, `SetAgentKnowledgeBaseAccess`, and KB-centric `UpsertKnowledgeBasePermission(subjectType=agent)` must require the acting user to own or control the target agent. Agent read/write repository access selections must not exceed the acting user's human-visible KB and effective repository-access capability. 3. **KB agent-access read disclosure guard**: `ListAgentAccessibleKnowledgeBases` must require owned-agent proof and fail closed when the ownership source is unavailable. 4. **Self-demotion guard**: Browser-facing KB permissions routes must require an explicit confirmation before accepting self-edits that narrow the acting user's KB role, KB-level repository access default, or repository-row effective profile. Confirmed submissions carry an explicit confirmation flag, and server-side validation must reject unconfirmed self-demotion attempts before forwarding them to the permission owner. 5. **Repository admin boundary**: A KB source repository `manage` profile may materialize AGS `admin`, but it must not grant KB `manage` or bypass KB product authorization. ## 8. Known boundaries that require separate ownership - Cross-workspace human grantee validation depends on a shared AgentTeam workspace membership authority. It should be solved through that shared authority rather than ad-hoc subject id checks inside `KBService`. - Direct MeshX exposure relies on deployment boundary and trusted-JWT policy. Browser routes enforce current-workspace authorization, but public/direct MeshX exposure must be audited separately. - Agent retrieval endpoints authorize through KB grant intersection plus agent-thread attestation or request agent id. Human owned-agent proof applies to human control-plane grant editing and agent-centric listing, not to runtime retrieval execution.