gRPC API Reference

service SecretsService {
  rpc Health(Empty) returns (HealthResponse);
  rpc StoreSecret(StoreSecretRequest) returns (StoreSecretResponse);
  rpc RequestSecretAccess(AccessRequest) returns (stream AccessResponse);
  rpc RequestUserSecret(UserSecretRequest) returns (stream AccessResponse);
  rpc ListSecrets(ListSecretsRequest) returns (ListSecretsResponse);
  rpc DeleteSecret(DeleteSecretRequest) returns (DeleteSecretResponse);
  rpc GetAuditLog(AuditLogRequest) returns (stream AuditLogEntry);
}

message HealthResponse {
  bool healthy = 1;
  string version = 2;
  uint64 uptime_seconds = 3;
}

message StoreSecretRequest {
  string name = 1;
  string value = 2;           // Plaintext — encrypted at rest
  SecretType secret_type = 3;
  map<string, string> metadata = 4;
}

message StoreSecretResponse {
  string secret_id = 1;
  bool success = 2;
  string error = 3;
}

message AccessRequest {
  string secret_name = 1;
  string tool_name = 2;       // Which tool needs the secret
  string reason = 3;          // Context shown to the user
  AccessDuration duration = 4;
}

message AccessResponse {
  AccessStatus status = 1;    // PENDING, APPROVED, DENIED, EXPIRED
  string token = 2;           // One-time access token (on APPROVED)
  string error = 3;
}

message UserSecretRequest {
  string prompt = 1;          // What to ask the user
  string tool_name = 2;
  string reason = 3;
}

message ListSecretsResponse {
  repeated SecretMetadata secrets = 1;
}

message SecretMetadata {
  string id = 1;
  string name = 2;
  SecretType secret_type = 3;
  int64 created_at = 4;
  int64 last_accessed = 5;
}

message DeleteSecretRequest {
  string secret_id = 1;
}

message DeleteSecretResponse {
  bool success = 1;
  string error = 2;
}

message AuditLogEntry {
  string entry_id = 1;
  string action = 2;          // STORE, ACCESS, APPROVE, DENY, DELETE
  string secret_name = 3;
  string actor = 4;           // Who performed the action
  int64 timestamp = 5;
  string previous_hash = 6;   // SHA-256 chain
  bytes signature = 7;        // Ed25519 signature
}