OpenShell/proto/credential_driver.proto

// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

package openshell.credentials.v1;

import "datamodel.proto";
import "google/protobuf/timestamp.proto";
import "extension.proto";

// Internal credential-driver contract used by the gateway.
//
// The gateway owns provider semantics and sandbox delivery. Credential drivers
// own backend-specific storage, deletion, authentication, and lookup for
// gateway-managed provider-secret handles. Secrets include injectable provider
// credentials and gateway-only refresh material.
service CredentialDriver {
  // Report driver identity and feature support.
  rpc GetCapabilities(GetCredentialDriverCapabilitiesRequest)
      returns (GetCredentialDriverCapabilitiesResponse);

  // Store or overwrite one gateway-managed provider secret and return an opaque handle.
  rpc StoreCredential(StoreCredentialRequest) returns (StoreCredentialResponse);

  // Delete one provider credential handle.
  rpc DeleteCredential(DeleteCredentialRequest) returns (DeleteCredentialResponse);

  // Resolve a batch of credential handles into string secret values.
  rpc ResolveCredentials(ResolveCredentialsRequest)
      returns (ResolveCredentialsResponse);

  // Optionally list discoverable credentials. Drivers may return UNIMPLEMENTED.
  rpc ListCredentials(ListCredentialsRequest) returns (ListCredentialsResponse);
}

message GetCredentialDriverCapabilitiesRequest {
  // Gateway protocol metadata. Drivers must reject unmet requirements.
  openshell.extension.v1.PeerMetadata gateway = 1;
}

message GetCredentialDriverCapabilitiesResponse {
  // Human-readable driver name.
  string driver_name = 1;
  // Deprecated diagnostic compatibility field. Use extension.implementation_version.
  string driver_version = 2;
  // Backend kind, such as "kubernetes-secrets" or "vault".
  string backend_kind = 3;
  // True when ListCredentials is supported.
  bool supports_list = 4;
  // True when ResolveCredentials may return expiration_time values.
  bool supports_expires_at = 5;
  // Credential-driver protocol metadata. Required for protocol negotiation.
  // Declare protocol 1.0 and list "openshell.credentials.contract" in
  // supported_capabilities.
  openshell.extension.v1.PeerMetadata extension = 6;
}

message StoreCredentialRequest {
  // Provider instance name supplied for audit and backend policy decisions.
  string provider = 1;
  // Gateway-owned logical key for this provider secret. Injectable credentials
  // use their runtime environment key; refresh material uses an internal key.
  string credential_key = 2;
  // Secret value to store. Drivers must never log this field.
  string value = 3;
  // Existing handle to overwrite, if any.
  openshell.datamodel.v1.CredentialHandle existing_handle = 4;
  // Workspace that owns this provider. Used to ensure cross-workspace uniqueness.
  string workspace = 5;
  // Provider UUID. Combined with workspace to ensure globally unique backend paths.
  string provider_id = 6;
  // Per-write backend object identity. When empty, drivers use provider_id.
  // Refreshes set this to a unique value so a staged write cannot overwrite the
  // currently committed object while provider_id remains the immutable owner.
  string object_id = 7;
}

message StoreCredentialResponse {
  // Opaque handle for later resolution/deletion.
  openshell.datamodel.v1.CredentialHandle handle = 1;
}

message DeleteCredentialRequest {
  // Provider instance name supplied for audit and backend policy decisions.
  string provider = 1;
  // Gateway-owned logical key that owns the handle.
  string credential_key = 2;
  // Opaque handle to delete.
  openshell.datamodel.v1.CredentialHandle handle = 3;
  // Workspace that owns this provider. Used to ensure cross-workspace uniqueness.
  string workspace = 4;
  // Provider UUID. Combined with workspace to ensure globally unique backend paths.
  string provider_id = 5;
}

message DeleteCredentialResponse {}

message ResolveCredentialsRequest {
  repeated ResolveCredentialRequest credentials = 1;
}

message ResolveCredentialRequest {
  // Gateway-chosen opaque ID used to correlate batch responses.
  string request_id = 1;
  // Provider instance name supplied for audit and backend policy decisions.
  string provider = 2;
  // Gateway-owned logical key for the value being resolved.
  string credential_key = 3;
  // Opaque handle to resolve.
  openshell.datamodel.v1.CredentialHandle handle = 4;
  // Workspace that owns this provider. Used to ensure cross-workspace uniqueness.
  string workspace = 5;
  // Provider UUID. Combined with workspace to ensure globally unique backend paths.
  string provider_id = 6;
}

message ResolveCredentialsResponse {
  repeated ResolvedCredential credentials = 1;
}

message ResolvedCredential {
  reserved 3;
  reserved "expires_at_ms";
  // Echoes ResolveCredentialRequest.request_id.
  string request_id = 1;
  // Secret string value. Drivers must never log this field.
  string value = 2;
  // Expiration time. Absence means the credential does not expire.
  google.protobuf.Timestamp expiration_time = 103;
}

message ListCredentialsRequest {}

message ListCredentialsResponse {
  repeated ListedCredential credentials = 1;
}

message ListedCredential {
  // Opaque handle identifier or driver-owned display name.
  string handle = 1;
  // Available credential keys under the backend object.
  repeated string keys = 2;
  // Driver-owned non-secret metadata.
  map<string, string> metadata = 3;
}