Add identity-bound CAS and secret-free attestation for provider mutations

[cjagwani]

Problem Statement

Provider automation cannot currently bind a credential/config mutation atomically to the provider identity it inspected.

In OpenShell v0.0.104 (dd2b4e3bc0688bdd59f90030f7c1d52511d6e354):

• openshell provider list --output json returns a useful secret-free identity view (id, name, workspace, type, credential/config key names, and resource_version).
• The gateway supports client-driven optimistic concurrency when Provider.metadata.resource_version is non-zero.
• The provider update CLI always sends an empty provider ID and resource_version: 0.
• The gateway therefore resolves the provider by name at mutation time and CASes against the version it just read, rather than an identity/version previously observed by the caller.

If a provider is updated or deleted/recreated between an automation client's read and update, the new identity can receive the submitted credential/config before a client-side post-read detects drift. A post-mutation receipt cannot undo that credential delivery.

This blocks fail-closed consumers that need multiple endpoint-bound providers, including NemoClaw's judge/weak/strong model targets for native Hermes → NeMo Relay → Switchyard routing (NVIDIA/NemoClaw#8887).

The current secret-free inventory also cannot attest endpoint configuration or the resolved provider-profile revision: it intentionally exposes config key names but not a non-secret config digest or profile provenance. Consequently, callers cannot distinguish two same-shaped providers targeting different endpoints.

Proposed Design

Add an identity-bound conditional mutation contract to the provider API and CLI.

1. Extend provider update with explicit expected identity fields, for example:
   • expected_provider_id
   • expected_resource_version
2. Expose corresponding CLI flags, such as:
   • openshell provider update NAME --expected-id ID --expected-resource-version N ...
3. Validate both fields against the current record before preparing or storing any submitted credential material.
4. Preserve the existing unconditional behavior only when neither expectation is supplied; reject partial expectation pairs.
5. Return a machine-readable, secret-free mutation receipt from create/update and a matching read surface containing:
   • provider ID, name, workspace, type, and resource version;
   • credential/config key names, never values;
   • resolved profile ID, scope/workspace, and profile resource version;
   • a versioned digest of canonical non-secret provider config (or another stable endpoint/config attestation).

The receipt should be generated by the gateway from the committed record, not reconstructed by the CLI.

Security Requirements

• A stale expected provider ID or resource version fails before any new credential reaches persistent or external credential storage.
• A concurrent delete/recreate under the same name cannot satisfy an update authorized for the old provider, even if its numeric resource version happens to match.
• Errors and structured output never contain credential values or credential-store handles.
• The config attestation format is versioned and deterministic; unknown/unsupported versions fail closed for consumers that require it.
• Profile provenance is resolved at the same gateway snapshot used for the mutation receipt.

Acceptance

• CLI and API can conditionally update a provider by exact ID plus resource version.
• Concurrent update and delete/recreate tests prove stale mutations do not persist or deliver submitted credentials.
• Successful create/update returns a secret-free receipt bound to the committed identity/version.
• A read API exposes the same attestation fields without credential values.
• Same-shaped providers with different endpoint config produce different config attestations.
• Resolved provider-profile revision/scope drift is observable.
• Backward-compatible unconditional updates remain explicitly documented, while security-sensitive automation can require the conditional path.

Alternatives Considered

Client-side read → update → read: detects some drift after the fact but cannot prevent credential delivery to the wrong identity.

Resource version without provider ID: does not fully protect delete/recreate under the same name when versions coincide.

Expose raw provider config: unnecessary for the transaction and can expand disclosure. A stable versioned digest plus resolved profile provenance is sufficient for exact automation checks.

Checklist

• Existing issues were searched for provider CAS, expected resource version, concurrent provider update, and provider attestation.
• The current CLI, proto, gateway update path, and concurrency tests were inspected.
• This is a design/API request, not a request to expose credentials.

[cjagwani]

Implementation audit — strict RPC and credential-staging boundary

I traced the current-main gateway, persistence CAS, credential-driver, CLI, and TUI paths.

The existing primitives can securely guarantee that a stale credential is never attached to or resolvable through the wrong provider identity:

1. expose a new strict conditional-update RPC whose request requires both expected provider ID and expected resource version;
2. read and validate the exact identity/version;
3. stage submitted credentials under fresh, unreferenced handles;
4. CAS the original provider record by stable ID/version;
5. delete staged handles on CAS failure and old handles after success;
6. return a gateway-authored attestation from the committed record and the exact profile-catalog snapshot used for validation.

A new RPC is safer than only adding protobuf fields to the legacy update method: an older gateway then returns UNIMPLEMENTED before handling the mutation instead of ignoring unknown expectation fields and performing an unconditional update. The current update RPC can remain explicitly legacy/unconditional.

The attestation can remain secret-free while carrying provider identity/version, sorted credential and config key names, a versioned length-prefixed SHA-256 digest of canonical non-secret config, and resolved profile identity/scope/source/resource revision.

One acceptance detail needs maintainer clarification. Fresh staging plus database CAS prevents stale secrets from becoming reachable through a provider, but an external credential backend can transiently hold an unreferenced staged value before a racing CAS failure removes it. If the requirement means never attached or resolvable by the wrong provider, the current architecture supports the strict path. If it literally means never written to external credential storage before CAS, this requires a broader cross-replica reservation/fence or transactional credential-driver prepare/commit contract. A process-local mutex is insufficient for multi-replica gateways.

The focused test boundary should include partial expectations, wrong ID with a matching numeric version, stale version, delete/recreate, two concurrent strict updates with one winner, staged-handle cleanup, rotation ordering, deterministic/different config digests, profile provenance drift, and old-gateway UNIMPLEMENTED behavior.

[krishicks]

It's difficult for me to understand what the use case here is; I gather it's something that NemoClaw is doing, but can you restate the behavior NemoClaw is expecting to exercise here?

[cjagwani]

The concrete NemoClaw operation is onboarding and rotating the three provider bindings used by native Hermes → Relay → Switchyard routing:

• classifier/judge;
• weak/fast;
• strong/quality.

NemoClaw needs to read each provider's identity, endpoint/profile attestation, and resource version; submit updated config and credentials for that exact record; then persist the gateway-authored committed identity for generated Switchyard configuration and revision-bound placeholders.

The race we need to reject is:

1. NemoClaw reads provider weak as ID A / version 4.
2. Another actor updates it, or deletes A and recreates weak as ID B.
3. NemoClaw submits the credential intended for A.
4. Today's name-based unconditional CLI update can apply it to the current weak record before a post-read detects the drift.

The expected secure behavior is a conditional update that requires ID A + version 4 and fails before the credential becomes attached to or resolvable through any different provider. On success, the gateway returns the committed ID/version plus secret-free endpoint/profile attestation so NemoClaw can verify and persist the exact binding. On mismatch, NemoClaw fails onboarding/rotation and leaves the previously working routing configuration intact.

This is also needed for rebuild and credential rotation: NemoClaw must prove that classifier, weak, and strong still refer to the endpoint-bound provider identities it qualified before enabling Hermes readiness. A name plus credential/config key names is insufficient because same-shaped providers can target different endpoints.

For the staging clarification: NemoClaw does not require that bytes can never transiently exist under a fresh unreferenced backend handle. It requires that a stale mutation can never attach the submitted secret to, or make it resolvable through, the wrong provider identity; staged handles must be deleted on CAS failure.

[krishicks]

Please restate the issue in terms of a persona using OpenShell; the above comment is so rooted in NemoClaw terminology and behavior it's unclear what it's actually doing with OpenShell. I'd like to see a clear user story that outlines a workflow within OpenShell that exposes a gap in current functionality. It shouldn't require anything specific to NemoClaw to define an actionable user story.