Tracking: generalize brokered credential delivery beyond inference.local and Microsoft S2S

Problem Statement

OpenShell has a strong broker pattern for LLM provider credentials through inference.local, and PR #1424 adds a concrete Microsoft S2S step. The same pattern should become a general credential-delivery architecture for IdP-issued dynamic tokens, downstream API tokens, refresh token custody, and consent-driven flows.

Proposed Design

1. Expose a stable internal broker surface such as credentials.local, with provider aliases only where they improve compatibility.
2. Acquire downstream credentials through the appropriate flow: client credentials, OBO, RFC 8693 token exchange, refresh, or async consent where the IdP supports it.
3. Cache, rotate, and revoke credentials gateway-side; never return downstream tokens to the sandbox.
4. Inject credentials on egress only for policy-approved hosts and tools.
5. Reject or strip sandbox-supplied Authorization headers for hosts configured as brokered, so a local shell or attacker-supplied credential cannot bypass broker policy.
6. Key broker decisions on attested workload identity where available. Treat DPoP or mTLS proof-of-possession as provider-scoped enhancements, not universal acceptance criteria.

Acceptance criteria:

• At least one non-LLM downstream API can be called without token material readable from inside the sandbox.
• Credential rotation completes without sandbox restart.
• Gateway-side revocation blocks subsequent use within one policy reload or documented revocation interval.
• Sandbox-supplied Authorization on brokered hosts is rejected or stripped, with a structured policy error.
• Broker decisions log agent_id, session_id, user_principal where applicable, tool/binary identity, requested scope/resource, granted scope/resource, decision, and correlation ID.

Sub-issues:

• #1754 Entra OBO token acquisition
• #1756 Scope attenuation for broker-issued downstream tokens
• #1757 Async user-consent broker for always-on agents
• #1758 OpenTelemetry trace correlation across gateway activity

Alternatives Considered

• Continue adding one provider-specific shim at a time: fastest locally, but risks uneven semantics and audit gaps.
• Rely only on network allowlists: controls destination, but not token scope, issuer, custody, or attribution.
• Let every tool manage its own credential cache: compatible, but puts credential material back into the sandbox trust boundary.

Agent Investigation

Problem. OpenShell has a strong broker pattern for LLM provider credentials through inference.local, and PR #1424 adds a concrete Microsoft S2S step. The same pattern should become a general credential-delivery architecture for IdP-issued dynamic tokens, downstream API tokens, refresh token custody, and consent-driven flows. This is a tracking/design issue. The most concrete sub-issue (Entra OBO) should be filed first and linked here.

Investigation:

• The inference.local model already proves credential brokering works at the gateway: sandbox-supplied credentials are stripped, backend credentials are injected at the proxy, and the agent never sees the upstream secret. This issue asks for that pattern to become a general delivery architecture.
• PR #1424 (microsoft-agent-s2s) is the second concrete instance of the pattern — confirming the broker extends from LLM keys to dynamic IdP-issued app tokens.
• Providers v2 supports oauth2_client_credentials, oauth2_refresh_token, google_service_account_jwt, static, and external refresh strategies today. All are machine-credential or pre-acquired-token shaped; none initiate user-context exchange (OBO) or async user consent (CIBA).
• The Providers v2 Roadmap explicitly lists "Automatic credential scope extraction" and "Refresh telemetry as OCSF events" as future work, directly motivating the scope-attenuation and OTel-correlation sub-issues.
• Current Providers v2 credential delivery still uses environment-variable placeholders resolved at the proxy. Acceptable for app S2S; insufficient for user-context tokens, which must not be readable from inside the sandbox under any path. A non-env-var delivery contract is part of the ask.

Current Documented Capability Map:

References:

• OpenShell architecture / inference.local: https://docs.nvidia.com/openshell/about/architecture
• OpenShell Providers v2: https://docs.nvidia.com/openshell/sandboxes/providers-v2
• OpenShell policy schema: https://docs.nvidia.com/openshell/reference/policy-schema
• OpenShell PR #1424: https://github.com/NVIDIA/OpenShell/pull/1424
• RFC 8693 (OAuth 2.0 Token Exchange): https://datatracker.ietf.org/doc/html/rfc8693

Checklist

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

Treat this as a tracking and design issue rather than an implementation task. Start with the architecture, Providers v2, and policy-schema documents, then review PR #1424 and the Entra OBO sub-issue #1754. Done requires a concrete broker architecture meeting the listed acceptance criteria, with implementation work split into the linked sub-issues.