docs(augment): expand permissions scope and make admin fallback opt-in

Address second round of PR review feedback on fine-grained permissions proposal:

- Add 5 infrastructure resource permissions (vectorstore, document, mcp, prompt,
  model) as basic permissions, expanding total from 16 to 21. These enable
  deployers to grant targeted access instead of all-or-nothing augment.admin.

- Add corresponding route authorization requirements for all 5 infrastructure
  categories, including closing the gap where MCP tool creation was ungated.

- Change augment.admin fallback from default-on to opt-in via
  permissions.legacyAdminFallback config flag. Dev preview means no backward
  compatibility guarantees — opt-in avoids the "temporary becomes permanent"
  problem where removing the fallback later becomes the breaking change it was
  meant to prevent. Existing deployments can enable the flag during migration.

- Update authorization-middleware spec with fallback-disabled scenarios and
  config-gated fallback behavior in authorizeLifecycleAction and
  authorizeBasicWithFallback.

- Update design.md context, goals, Decision 2, and risk mitigations to reflect
  broader scope and opt-in fallback rationale.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: gabemontero <gmontero@redhat.com>

Author: gabemontero

workspaces/augment/openspec/changes/fine-grained-backstage-permissions/design.md

@@ -2,7 +2,7 @@
 
 ## Context
 
-The augment plugin currently enforces 12+ authorization decisions via custom inline guards in route handlers — `checkIsAdmin`, `createdBy` comparisons, lifecycle stage checks, and self-approval prevention. These bypass Backstage's permission framework entirely. Only two coarse permissions exist (`augment.access` for read, `augment.admin` for admin operations), making fine-grained RBAC impossible.
+The augment plugin currently enforces 12+ authorization decisions via custom inline guards in route handlers — `checkIsAdmin`, `createdBy` comparisons, lifecycle stage checks, and self-approval prevention. These bypass Backstage's permission framework entirely. Only two coarse permissions exist (`augment.access` for read, `augment.admin` for admin operations), making fine-grained RBAC impossible. Additionally, all infrastructure operations (vector stores, documents, MCP connections, prompts, models) are gated by the single `augment.admin` permission, preventing deployers from granting targeted access to specific resource categories.
 
 Backstage provides a permission framework (`@backstage/plugin-permission-node`) supporting basic permissions, resource-based permissions with conditional rules, and policy evaluation via the permission backend. The `extensions-backend` plugin in this workspace already follows this pattern and serves as a reference implementation.
 
@@ -13,15 +13,15 @@ These permissions are independent of AgenticProvider authorization. Kagenti's pe
 **Goals:**
 
 - Replace all 12+ inline authorization decisions with Backstage permission framework calls
-- Enable deployers to configure fine-grained RBAC policies for agent and tool lifecycle operations
-- Maintain full backward compatibility — existing `augment.access` + `augment.admin` policies continue to work unchanged
+- Enable deployers to configure fine-grained RBAC policies for agent and tool lifecycle operations and targeted access to infrastructure resources (vector stores, documents, MCP connections, prompts, models)
+- Provide an opt-in legacy fallback (`permissions.legacyAdminFallback`) so existing deployments using `augment.access` + `augment.admin` can migrate incrementally
 - Support conditional permission rules for ownership checks, self-approval prevention, and lifecycle stage gating
 - Keep self-approval prevention as defense-in-depth (permission rule supplements hard-coded check)
 - Emit structured audit log entries for all authorization decisions — recording the user, action, resource, outcome (allow/deny), and whether the `augment.admin` fallback was used. The authorization middleware is the single point through which all permission decisions flow, making it the natural place for audit logging.
 
 **Non-Goals:**
 
-- Modifying `augment.access` or `augment.admin` behavior or semantics
+- Modifying `augment.access` or `augment.admin` behavior or semantics (though `augment.admin` is no longer the default gate for lifecycle/infrastructure operations)
 - Adding permissions for AgenticProvider-level operations (Kagenti API calls, OpenAI API calls)
 - Frontend permission checks (backend-only enforcement)
 - Custom permission policy plugins (works with standard Backstage RBAC)
@@ -35,13 +35,13 @@ Define `augment-agent` and `augment-tool` as distinct resource types rather than
 
 **Alternative considered:** Single `augment-resource` type with a discriminator field. Rejected because it conflates two domain objects that are independently routed and independently targetable by policy.
 
-### Decision 2: Two-tier authorization with backward-compatible fallback
+### Decision 2: Opt-in legacy fallback to `augment.admin`
 
-`authorizeLifecycleAction` checks the fine-grained permission first. If DENY (the default when no policy exists), it falls back to checking `augment.admin`. This means deployments that haven't configured fine-grained policies get identical behavior to today.
+When `permissions.legacyAdminFallback` is enabled in the plugin config, `authorizeLifecycleAction` checks the fine-grained permission first. If DENY, it falls back to checking `augment.admin`. When the config flag is absent or false (the default), only fine-grained permissions are evaluated — no fallback occurs.
 
-**Why backward compatibility matters for a "new" plugin:** Although the augment plugin is still in active development, there are external consumers already running it with RBAC policies configured around `augment.access` + `augment.admin`. From their perspective, a new drop that requires policy reconfiguration to maintain existing access is a cross-release breaking change. The fallback ensures these deployments continue to work on upgrade, while giving them the option to adopt fine-grained policies incrementally.
+**Why opt-in rather than default-on:** The augment plugin is in dev preview, which means no backward compatibility guarantees. Making the fallback default-on risks the "temporary becomes permanent" problem — once deployments rely on `augment.admin` as a catch-all, removing the fallback later becomes the very breaking change it was meant to prevent. Opt-in gives existing consumers a migration path (enable the flag, then incrementally adopt fine-grained policies, then disable the flag) without baking the fallback into every deployment's baseline.
 
-**Alternative considered:** Requiring all deployments to update their RBAC policies. Rejected because it would break existing augment deployments on upgrade — deployers would need to add fine-grained policy entries before the upgrade or lose access to lifecycle operations.
+**Alternative considered:** Default-on fallback for all deployments. Rejected because it creates invisible load-bearing behavior that becomes difficult to remove — every release the fallback ships as default makes removal harder, not easier. Dev preview is the right time to establish the clean model.
 
 **Alternative considered:** OR-combining fine-grained and admin in a single policy evaluation. Rejected because Backstage's permission framework evaluates permissions individually — the fallback must be explicit in code.
 
@@ -63,7 +63,7 @@ Permission rules (`IS_OWNER`, `IS_NOT_CREATOR`, `HAS_LIFECYCLE_STAGE`) follow th
 
 ## Risks / Trade-offs
 
-- **Policy migration complexity** → Deployers who want fine-grained control must write new RBAC policies. Mitigated by the fallback mechanism — no action required to maintain current behavior.
+- **Policy migration complexity** → Deployers must configure fine-grained RBAC policies. Existing deployments can enable `permissions.legacyAdminFallback` to preserve current `augment.admin` behavior during migration.
 - **Conditional evaluation overhead** → Resource-based permissions require loading the resource to evaluate conditions. Mitigated by keeping list operations as basic permissions and only using resource-based permissions for mutation routes where the resource is already loaded.
 - **Rule mismatch on upgrade** → If a deployer configures a fine-grained policy with a `HAS_LIFECYCLE_STAGE` condition referencing a stage name that changes, the rule silently denies. Mitigated by documenting stage names as part of the permission contract.
 - **Defense-in-depth dual check** → The self-approval hard-coded check and `IS_NOT_CREATOR` rule are redundant by design. If one is relaxed without updating the other, behavior may be confusing. Mitigated by documenting this clearly.

workspaces/augment/openspec/changes/fine-grained-backstage-permissions/specs/authorization-middleware/spec.md

@@ -2,40 +2,45 @@
 
 Augment-specific authorization middleware that integrates Backstage's permission framework with the plugin's domain model (agents, tools, lifecycle stages, ownership). This is NOT a reimplementation of RBAC policy evaluation — the RBAC plugin handles that. This middleware provides:
 
-1. **Two-tier fallback logic** — check fine-grained permission first, fall back to `augment.admin` for backward compatibility during migration. This is augment-specific business logic that the RBAC plugin cannot provide, since the fallback semantics (which coarse permission to check, when to check it) are domain decisions.
+1. **Opt-in legacy fallback logic** — when `permissions.legacyAdminFallback` is enabled, check fine-grained permission first, then fall back to `augment.admin` for backward compatibility during migration. When disabled (the default), only fine-grained permissions are evaluated. This is augment-specific business logic that the RBAC plugin cannot provide, since the fallback semantics (which coarse permission to check, when to check it) are domain decisions.
 2. **Conditional evaluation against augment resource types** — `matchesAgentConditions` and `matchesToolConditions` evaluate Backstage CONDITIONAL results against augment's domain objects (agents/tools with `createdBy`, lifecycle stages). The RBAC plugin evaluates policies; these utilities evaluate the resulting conditions against augment-specific resource shapes.
 3. **RouteContext integration** — exposing authorization functions on the route context so handlers can call them without importing permission utilities directly.
 
 ### Relationship to existing permissions
 
 - **`augment.access`** remains unchanged — it is a plugin-level visibility gate (can the user access the augment plugin at all?) and is orthogonal to fine-grained lifecycle permissions.
-- **`augment.admin`** continues to gate admin-only routes (config, documents, vector stores, models, evaluations, workflows, dev spaces) that are not covered by the fine-grained permissions. For agent/tool lifecycle operations, it serves as a backward-compatible fallback: existing deployments that only have `augment.admin` policies continue to work without reconfiguration. Deployers who adopt fine-grained permissions can remove the `augment.admin` grant for lifecycle operations — the fallback is a migration aid, not a permanent override.
+- **`augment.admin`** continues to gate admin-only routes (evaluations, workflows, dev spaces) that are not yet covered by fine-grained permissions. For agent/tool lifecycle operations and infrastructure resources (vector stores, documents, MCP, prompts, models), it can serve as a backward-compatible fallback when `permissions.legacyAdminFallback` is enabled in the plugin config. By default, only fine-grained permissions are evaluated — deployments must configure the appropriate fine-grained RBAC policies.
 
 ## ADDED Requirements
 
 ### Requirement: authorizeLifecycleAction function
 
-The system SHALL provide an `authorizeLifecycleAction(req, permission, resource?)` function that implements two-tier authorization:
+The system SHALL provide an `authorizeLifecycleAction(req, permission, resource?)` function that implements authorization with opt-in legacy fallback:
 
 1. Evaluate the fine-grained permission (with conditional rules if resource-based)
 2. If ALLOW, grant access
-3. If DENY, fall back to checking `augment.admin`
-4. If `augment.admin` is ALLOW, grant access
+3. If DENY and `permissions.legacyAdminFallback` is enabled, fall back to checking `augment.admin`
+4. If fallback is enabled and `augment.admin` is ALLOW, grant access
 5. Otherwise, deny access
 
 #### Scenario: Fine-grained permission allows
 
 - **WHEN** `authorizeLifecycleAction` is called and the fine-grained permission evaluates to ALLOW
 - **THEN** access SHALL be granted without checking `augment.admin`
 
-#### Scenario: Fine-grained denies but admin allows
+#### Scenario: Fine-grained denies, fallback enabled, admin allows
 
-- **WHEN** `authorizeLifecycleAction` is called, the fine-grained permission evaluates to DENY, and `augment.admin` evaluates to ALLOW
+- **WHEN** `authorizeLifecycleAction` is called, the fine-grained permission evaluates to DENY, `permissions.legacyAdminFallback` is enabled, and `augment.admin` evaluates to ALLOW
 - **THEN** access SHALL be granted via the fallback
 
-#### Scenario: Both deny
+#### Scenario: Fine-grained denies, fallback disabled
 
-- **WHEN** `authorizeLifecycleAction` is called and both the fine-grained permission and `augment.admin` evaluate to DENY
+- **WHEN** `authorizeLifecycleAction` is called, the fine-grained permission evaluates to DENY, and `permissions.legacyAdminFallback` is not enabled
+- **THEN** access SHALL be denied without checking `augment.admin`
+
+#### Scenario: Both deny with fallback enabled
+
+- **WHEN** `authorizeLifecycleAction` is called, `permissions.legacyAdminFallback` is enabled, and both the fine-grained permission and `augment.admin` evaluate to DENY
 - **THEN** access SHALL be denied
 
 ### Requirement: Conditional permission evaluation
@@ -50,21 +55,26 @@ When `authorizeLifecycleAction` receives a CONDITIONAL result from the permissio
 #### Scenario: Conditional result with non-matching resource
 
 - **WHEN** the permission framework returns CONDITIONAL with an `IS_OWNER` condition, and the resource's `createdBy` does not match the requesting user
-- **THEN** `authorizeLifecycleAction` SHALL evaluate the condition to DENY and fall back to `augment.admin`
+- **THEN** `authorizeLifecycleAction` SHALL evaluate the condition to DENY and, if `permissions.legacyAdminFallback` is enabled, fall back to `augment.admin`
 
 ### Requirement: authorizeBasicWithFallback function
 
-The system SHALL provide an `authorizeBasicWithFallback(req, permission)` function for basic (non-resource) permissions that checks the given permission first, then falls back to `augment.admin` on DENY.
+The system SHALL provide an `authorizeBasicWithFallback(req, permission)` function for basic (non-resource) permissions that checks the given permission first. If DENY and `permissions.legacyAdminFallback` is enabled, it falls back to `augment.admin`.
 
 #### Scenario: Basic permission allows
 
 - **WHEN** `authorizeBasicWithFallback` is called and the basic permission evaluates to ALLOW
 - **THEN** access SHALL be granted
 
-#### Scenario: Basic permission denies with admin fallback
+#### Scenario: Basic permission denies, fallback enabled, admin allows
 
-- **WHEN** `authorizeBasicWithFallback` is called, the basic permission evaluates to DENY, and `augment.admin` evaluates to ALLOW
-- **THEN** access SHALL be granted
+- **WHEN** `authorizeBasicWithFallback` is called, the basic permission evaluates to DENY, `permissions.legacyAdminFallback` is enabled, and `augment.admin` evaluates to ALLOW
+- **THEN** access SHALL be granted via the fallback
+
+#### Scenario: Basic permission denies, fallback disabled
+
+- **WHEN** `authorizeBasicWithFallback` is called, the basic permission evaluates to DENY, and `permissions.legacyAdminFallback` is not enabled
+- **THEN** access SHALL be denied without checking `augment.admin`
 
 ### Requirement: Authorization functions on RouteContext
 

workspaces/augment/openspec/changes/fine-grained-backstage-permissions/specs/permission-definitions/spec.md

@@ -2,11 +2,12 @@
 
 Fine-grained permission constants, resource types, and permission rule definitions for augment agent and tool governance.
 
-### Scope: Why agents and tools first
+### Scope
 
-This spec defines fine-grained permissions for **agent and tool lifecycle operations** because these are the authorization decisions with the most nuanced requirements — ownership scoping, self-approval prevention, lifecycle stage gating, and filtered visibility. These are currently enforced via inline checks (`checkIsAdmin`, `createdBy` comparisons) that bypass the Backstage permission framework entirely.
+This spec defines two tiers of fine-grained permissions:
 
-Other admin-only operations (config CRUD, document management, vector stores, models, evaluations, workflows, dev spaces) remain gated by the existing `augment.admin` permission. These are genuinely admin-only operations without ownership or conditional logic — the coarse gate is appropriate and adding fine-grained permissions for them today would increase surface area without clear demand. They are candidates for future fine-grained permissions if deployer requirements emerge (e.g., separating "can manage documents" from "can manage evaluations").
+1. **Resource-based permissions** for agents and tools — these have the most nuanced authorization requirements (ownership scoping, self-approval prevention, lifecycle stage gating, filtered visibility) and support conditional rules (`IS_OWNER`, `IS_NOT_CREATOR`, `HAS_LIFECYCLE_STAGE`).
+2. **Basic permissions** for infrastructure resources (vector stores, documents, MCP connections, prompts, models) — these are currently admin-only operations without ownership or lifecycle logic. Defining permissions for them now enables deployers to grant targeted access (e.g., "this team can manage vector stores but not MCP connections") instead of the all-or-nothing `augment.admin`. These can be upgraded to resource-based permissions later if ownership tracking is added.
 
 ## ADDED Requirements
 
@@ -83,9 +84,33 @@ The system SHALL define `augment.kagenti.admin` as a basic permission with actio
 - **WHEN** the `augment-common` package is loaded
 - **THEN** `augment.kagenti.admin` SHALL be a basic permission with action `update`
 
+### Requirement: Infrastructure resource permissions
+
+The system SHALL define the following basic permissions (no resource type) for infrastructure operations that are currently gated by `augment.admin`:
+
+| Permission ID                | Action | Gates                                                       |
+| ---------------------------- | ------ | ----------------------------------------------------------- |
+| `augment.vectorstore.manage` | update | Vector store CRUD (create, connect, disconnect, delete)     |
+| `augment.document.manage`    | update | Document upload and deletion within vector stores           |
+| `augment.mcp.manage`         | update | MCP connection testing, tool creation, deletion, and builds |
+| `augment.prompt.manage`      | update | System prompt generation and configuration                  |
+| `augment.model.manage`       | update | Model listing, testing, and selection configuration         |
+
+These are basic permissions without conditional rules. Each gates a category of admin operations, enabling deployers to grant targeted access without granting full `augment.admin`.
+
+#### Scenario: All infrastructure permissions defined
+
+- **WHEN** the `augment-common` package is loaded
+- **THEN** all 5 infrastructure permissions SHALL be defined as basic permissions with action `update`
+
+#### Scenario: Infrastructure permissions independent of augment.admin
+
+- **WHEN** a user has `augment.vectorstore.manage` but not `augment.admin`
+- **THEN** the user SHALL be able to manage vector stores but not other admin operations
+
 ### Requirement: Existing permissions preserved
 
-The existing `augmentAccessPermission` (`augment.access`) and `augmentAdminPermission` (`augment.admin`) SHALL remain unchanged. All 16 new permissions SHALL be added to the `augmentPermissions` array alongside the existing ones.
+The existing `augmentAccessPermission` (`augment.access`) and `augmentAdminPermission` (`augment.admin`) SHALL remain unchanged. All 21 new permissions SHALL be added to the `augmentPermissions` array alongside the existing ones. `augment.admin` continues to gate routes not yet covered by fine-grained permissions (evaluations, workflows, dev spaces) and serves as an opt-in fallback for fine-grained operations when `permissions.legacyAdminFallback` is enabled.
 
 #### Scenario: Backward-compatible exports