Add scope attenuation for broker-issued downstream tokens #1756

Problem Statement

A credential broker should mint or exchange downstream tokens with the minimum scope required by the calling agent/tool/binary. Without attenuation, a compromised hop can receive broader delegation than it needs, even if token custody remains gateway-side. Attenuation is what makes the broker pattern actually implement least-privilege delegation rather than just credential isolation.

Proposed Design

1. Add a scope_policy block per brokered host, provider, tool, or binary.
2. When the broker mints or exchanges a token, request only the declared scope/permission set for the calling identity.
3. Deny scope escalation with a structured error that includes requested scope, allowed scope, policy rule, and reason.
4. Support provider-specific permission models, such as Graph scopes and GitHub App installation permissions, rather than forcing all providers into OAuth scope strings.

Acceptance criteria:

• A Graph token issued for a read-only mail tool cannot be used for write scopes if the policy grants read-only access.
• A GitHub App token issued for issue listing uses read-level Issues/Metadata permissions rather than broad repository write permissions.
• scope_policy is declared in policy, supports reload without sandbox recreation, and is included in broker decision logs.
• Denied escalation attempts return structured errors the agent can report without exposing token material.

Alternatives Considered

• Use host-only policy: blocks some destinations, but cannot express least-privilege API permissions.
• Reuse the full incoming user token: simple, but gives each hop too much delegated authority.
• Create separate static credentials per tool: workable for some services, but hard to rotate and audit consistently.

Agent Investigation

• OpenShell network policy controls destination and HTTP access shape, but OAuth/API scopes are a separate authorization surface.
• The L7 access preset vocabulary is method-oriented, while downstream APIs such as Microsoft Graph and GitHub App installations have their own permission/scope models.
• The Providers v2 Roadmap lists "Automatic credential scope extraction" as future work, indicating no scope-aware logic exists in the current credential path.

References:

• OpenShell policy schema: https://docs.nvidia.com/openshell/reference/policy-schema
• OpenShell Providers v2 (Roadmap): https://docs.nvidia.com/openshell/sandboxes/providers-v2
• RFC 6749 (OAuth 2.0 Authorization Framework, scopes): https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
• RFC 8693 (OAuth 2.0 Token Exchange): https://datatracker.ietf.org/doc/html/rfc8693
• GitHub OAuth Apps scope vocabulary (example of OAuth scope model): https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
• GitHub App installation permissions (example of fine-grained model): https://docs.github.com/en/rest/overview/permissions-required-for-github-apps
• Microsoft Graph permissions reference (example of provider-specific scopes): https://learn.microsoft.com/en-us/graph/permissions-reference

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request