feat: add a core agent identity blueprint contract with Okta and Entra references

## Problem Statement

OpenShell experiments for Okta gateway login, runtime provider refresh, RFC 8693 token exchange, and Cross App Access established useful agent identity flows, but landing vendor-specific implementations directly in OpenShell would make the runtime own integration policy, deployment, and lifecycle for every identity provider.

NemoClaw is the opinionated blueprint layer that already composes OpenShell provider profiles, policy, credentials, sandbox lifecycle, and agent packaging. It should provide the supported reference architecture for agent identity instead. Today it has bundled static provider profiles and robust provider lifecycle handling, but no complete reference that separates and composes:

- application-user authentication and consent;
- OpenShell gateway administrator or automation authentication;
- backend service identity for sandbox and provider management;
- sandbox workload identity;
- delegated user credentials for an agent calling an approved API on behalf of that user.

Without a reference, integrations tend to reuse the gateway login token as the delegated subject, put OAuth custody in an ad hoc sidecar, or expose bearer material to the agent. The existing ID.me beta and NemoClaw Community Entra/Graph example demonstrate the desired identity boundaries, but they use standalone deployment and token-manager machinery that should become a repeatable NemoClaw shape.

## Desired Behavior

NemoClaw core owns a versioned, provider-neutral agent identity reference contract. Okta and Microsoft Entra are its first product-owned conformance implementations, not an exclusive support boundary. ID.me, Ping, Palo Alto Networks, XAA.dev, and other standards-based providers are eligible for core when they satisfy the same product scope, ownership, lifecycle, compatibility, security, validation, and conformance requirements. NemoClaw Community remains an optional incubation path rather than the default destination for providers outside the first two implementations.

An operator can select a conforming reference and obtain a complete, inspectable deployment that uses OpenShell primitives for provider custody, policy-derived egress, credential injection, and middleware enforcement.

Each reference must keep these principals separate:

1. The application user authenticates with the IdP and consents to a bounded downstream API scope.
2. The application backend authenticates to the OpenShell control plane with its own service identity and manages only its authorized providers and sandboxes.
3. OpenShell administrators authenticate to the gateway through a separate OIDC client and role/scope mapping. Gateway login is optional for the delegated runtime flow and is never used implicitly as the application's subject token.
4. The sandbox supervisor uses its OpenShell-issued sandbox identity.
5. The agent receives only an OpenShell placeholder. It never receives an access token, refresh token, ID token, client secret, private key, or gateway administrator token.

For each of Okta and Entra, the reference should provide one concrete end-to-end workflow:

- configure generic OpenShell gateway OIDC claim mapping for the provider;
- complete an application-user authorization flow outside the sandbox;
- transfer the current access token, expiry, and refresh/delegation material into an explicitly user-scoped OpenShell provider;
- import a bundled Providers v2 profile that owns the exact API endpoints, L7 rules, allowed binaries, credential placement, and refresh/token-grant metadata;
- attach the provider to one sandbox through NemoClaw lifecycle state;
- call an approved downstream API through the OpenShell proxy with the current delegated credential injected after middleware;
- rotate or exchange the credential without changing the agent-visible placeholder;
- revoke and delete the user-scoped provider on logout, consent withdrawal, timeout, ownership change, or sandbox removal;
- expose secret-safe provider refresh status, middleware findings, and OpenShell OCSF audit evidence.

The references should use the supervisor middleware contract from NVIDIA/OpenShell#2027 in substantially its current shape:

- middleware runs after network/L7 admission and before provider credential injection;
- it receives request, sandbox, and originating-process context but not OpenShell-managed credentials;
- it may allow, deny, transform admitted content, emit findings, and add only approved namespaced headers;
- `Authorization`, cookies, credential headers, routing headers, and framing headers remain protected;
- the identity policy stage defaults to `fail_closed` for matching protected API hosts.

Middleware should enforce request-aware identity policy and produce non-secret context. Providers v2 remains the only component that mints, stores, refreshes, resolves, and injects credentials. Do not return bearer tokens in middleware metadata, findings, body mutations, or namespaced headers.

## Constraints and Non-goals

- Assume NVIDIA/OpenShell#2027 lands in relatively its current shape. Pin the first compatible OpenShell release in the blueprint and remove the pin only through the normal compatibility process.
- Current Providers v2 supports OAuth2 refresh-token and client-credentials refresh plus SPIFFE JWT-SVID token grants, but not a general request-aware RFC 8693 OBO source. NVIDIA/OpenShell#1736 tracks dynamic identity sources for token exchange. The reference must either depend on the smallest accepted upstream capability from that issue or clearly stage OBO as blocked; it must not add an Okta-only or Entra-only token-exchange engine to NemoClaw.
- Current middleware cannot write `Authorization` and has no credential-resolution result. Preserve that boundary. If request-derived context must select a delegated grant, propose a non-secret handoff from middleware to Providers v2 or a separate credential resolver contract in OpenShell.
- Do not capture the OpenShell CLI gateway-login token as delegated provider material. The application-user flow and control-plane login flow are independent even when the same human and IdP participate in both.
- Core eligibility is based on conformance and sustained ownership, not provider market position. Okta and Entra establish the contract first; subsequent providers may land directly in core when their proposal names an owner and proves the same lifecycle, security, compatibility, validation, and maintenance commitments. NemoClaw Community may incubate incomplete or independently maintained variants but is not a permanent second-class tier.
- Do not create a public NemoClaw plugin SDK, arbitrary executable extension point, identity CRD, custom controller, or vendor-specific OpenShell authentication subsystem.
- Do not claim production certification for an IdP tenant. Local mock services and browser flows are acceptance tools; production requires HTTPS, durable encrypted state, tenant isolation, revocation, audit export, backup/recovery, and IdP-specific review.

## Implementation Idea

Use existing repository-owned seams before adding a new abstraction:

1. Add reviewed Okta and Entra Providers v2 profiles under `nemoclaw-blueprint/provider-profiles/`. Follow the existing Brave and Tavily import-before-create path. Profiles contain no secrets and declare only destination-specific credential placement, refresh/grant metadata, endpoint policy, and allowed binaries.
2. Add a strict, repository-owned identity-reference manifest consumed by the existing blueprint plan/apply path. It should compose an identity flow, IdP adapter, resource profile, deployment profile, and reference scenario while naming the provider profile, gateway OIDC mapping, external middleware service registration, policy attachment, provider ownership, and cleanup behavior. Treat it as an internal data contract until at least Okta and Entra prove the same fields are needed; do not expose arbitrary executable hooks or promise a public plugin SDK.
3. Package the identity policy/broker service as a reviewed NemoClaw component reachable by both the gateway and sandbox supervisors. Register it statically in the OpenShell gateway TOML as required by NVIDIA/OpenShell#2027, start it before the gateway, and include it in health, reconcile, rebuild, and removal behavior. Service upgrades must restart the gateway and reconcile running supervisors; do not assume an in-place service change at the same endpoint refreshes cached manifests.
4. Keep application OAuth bootstrap outside the sandbox. For a local reference, use a minimal host service or reference application that completes Authorization Code + PKCE or device authorization, validates issuer/audience/nonce/state, maps the immutable subject to an opaque provider name, transfers custody to OpenShell, and clears its local token bundle after successful transfer.
5. Extend NemoClaw's provider lifecycle state to preserve the selected profile, opaque provider name, attachment, middleware registration, and non-secret identity configuration across rebuild and restore. Never persist raw token material in NemoClaw host state, manifests, generated config, logs, or backups.
6. Use one mock standards-compliant IdP/resource server test fixture for deterministic CI, then retain separate manual acceptance checklists for real Okta and Entra tenants.

The initial implementation should define the smallest internal composition contract needed by two explicit references, not a public provider plugin framework. Okta and Entra prove that the contract is provider-neutral. Further IdPs should add data-only adapters and resource profiles wherever the standards permit, with code reserved for genuinely distinct protocol behavior.

## Acceptance Criteria

- [ ] Okta and Entra references each complete one application-user-to-agent delegated API call through an OpenShell sandbox.
- [ ] Gateway administrator login and application-user delegation use separate clients, tokens, storage, and configuration.
- [ ] The agent and sandbox-visible configuration contain placeholders only; raw OAuth tokens, client secrets, private keys, gateway tokens, and middleware service credentials are absent from environment dumps, process arguments, generated files, logs, snapshots, and backups.
- [ ] Providers v2 profiles are bundled, linted, imported before provider creation, attached explicitly, and composed into the effective sandbox policy.
- [ ] Provider endpoints and L7 paths are least privilege; credential injection occurs only on matching inspected requests from allowed binaries.
- [ ] Middleware policy applies before credential injection, defaults to fail closed for protected hosts, and cannot inspect or mutate protected credential headers.
- [ ] Token refresh or exchange updates the provider without changing the agent-visible placeholder or restarting the sandbox process that initiates new requests.
- [ ] Logout, revocation, timeout, sandbox removal, interrupted onboarding, rebuild, and restore have deterministic provider and middleware cleanup/recovery behavior.
- [ ] CI covers import failure, middleware outage, expired/revoked grant, subject/provider ownership mismatch, refresh rotation, provider attachment conflicts, and secret-negative assertions.
- [ ] Manual Okta and Entra acceptance evidence distinguishes browser authentication from automated proof and contains no token or personal-data payloads.
- [ ] Documentation includes the five-principal trust model, deployment topology, IdP setup worksheet, supported OpenShell version, troubleshooting, security boundaries, and conformance-based core admission policy.
- [ ] An adapter authoring guide and conformance tests show how ID.me, Ping, Palo Alto Networks, XAA.dev, and similar providers can implement the contract without adding provider-specific code to OpenShell.

## Alternatives Considered

**Land each IdP in OpenShell.** Rejected because generic OIDC gateway authentication, supervisor middleware, and Providers v2 are the reusable runtime primitives. Vendor deployment, consent, lifecycle, and reference application choices belong in the blueprint layer.

**Route providers to core or community by vendor.** Rejected because provider popularity is not an architectural boundary. Core support does imply lifecycle, compatibility, security, validation, and ownership commitments, so admission remains deliberate; however, any provider that satisfies those requirements can be maintained in core. Community is useful for incubation and independent ownership, not as the default home for every provider after Okta and Entra.

**Let middleware mint and inject bearer tokens.** Rejected because NVIDIA/OpenShell#2027 intentionally runs before credential injection, omits protected headers, and forbids `Authorization` mutation. Mixing policy inspection with secret-bearing credential injection would weaken the trust boundary.

**Reuse the OpenShell gateway login token for OBO.** Rejected because control-plane authorization and application-user delegation have different audiences, scopes, storage, revocation, and ownership. The ID.me reference demonstrates the safer separation.

**Keep an opaque token-manager sidecar per integration.** Useful as prior art and a temporary community implementation, but not the target. It duplicates provider custody, refresh, policy, observability, and recovery already owned by OpenShell.

## Agent Investigation

- Reviewed the ID.me OpenShell Minikube beta (`NVIDIA-dev/idme-openshell-minikube-demo`). Its strongest reusable contract is separation of application user, gateway administrator, backend service, sandbox supervisor, and agent identities, followed by explicit delegated credential custody transfer into OpenShell.
- Reviewed stale OpenShell PRs NVIDIA/OpenShell#1672 (Okta gateway login), NVIDIA/OpenShell#1673 (Okta runtime refresh profile), NVIDIA/OpenShell#1681 (Okta RFC 8693 OBO), and NVIDIA/OpenShell#1682 (Okta/XAA sample). Their provider profiles and tutorials are useful input, but NVIDIA/OpenShell#1681 and NVIDIA/OpenShell#1682 couple delegation to the gateway-login subject token and add provider-specific refresh strategies that should not be copied into NemoClaw.
- Reviewed NVIDIA/OpenShell#2027 and RFC 0009. The current API is an ordered `HttpRequest/pre_credentials` policy and transformation hook with static external-service registration, host selectors, body limits, strict header protections, findings, and fail-open/fail-closed behavior. It is a policy/context seam, not a credential provider API.
- Reviewed Providers v2 in current OpenShell. It already supplies custom profile import/update, provider-owned network policy, attach/detach lifecycle, refresh material custody, short-lived credential rotation, dynamic SPIFFE token grants, and proxy injection. The missing OBO capability is dynamic user/actor identity sourcing, tracked by NVIDIA/OpenShell#1736.
- Reviewed current NemoClaw `origin/main`. The closest core precedent is `nemoclaw-blueprint/provider-profiles/` plus `src/lib/actions/credentials-add.ts` and `src/lib/onboard/brave-provider-profile.ts`, which import bundled data-only profiles before provider creation and preserve provider lifecycle through onboarding/rebuild.
- Reviewed `NVIDIA/nemoclaw-community`. `examples/personal-community-sentiment-triage/` is the closest full reference architecture: explicit host services, gateway, providers, sandbox, policy, agent assets, bring-up/tear-down, and Entra/Graph token-manager lifecycle. It is useful packaging precedent and demonstrates behavior that core references can simplify with Providers v2.
- Searched NemoClaw issues for Okta, OBO, OAuth, and identity-provider references. No existing issue covers this proposal; closed #58 concerns Azure-hosted inference rather than delegated agent identity.

## Category

Provider

Start with the existing blueprint plan/apply path and the provider-profiles/ directory, following the Brave and Tavily import-before-create flow. Read the supervisor middleware contract in OpenShell#2027 and the dynamic identity-source work in OpenShell#1736 before defining the internal manifest and lifecycle state. Done means Okta and Entra references pass the listed mock CI scenarios and manual acceptance checks without exposing secrets, while preserving cleanup and rebuild behavior.

Written by the indexing model from the issue text.