// Copyright 2026 EngFlow, Inc. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package engflow.secret.v1;

option go_package = "github.com/EngFlow/engflowapis/go/engflow/secret/v1;secretv1";

option java_multiple_files = true;
option java_outer_classname = "SecretProtos";
option java_package = "com.engflow.secret.v1.proto";

// The Secret service provides a way to manage secrets on an EngFlow instance
// (also known as a tenant). Secrets are shared by all users within an instance,
// so this service is only appropriate for values not specific to individual
// users.
//
// Secrets stored here may be made available to remotely executed actions. To
// use a secret, set the "engflow:secrets" platform property to a
// comma-separated list of secret names. Each named secret will be exposed
// to the action as an environment variable. Actions that cannot use environment
// variables, namely persistent worker actions, cannot use secrets.
//
// To be able to read and write secrets, the client must have permission,
// granted via EngFlow's Identity and Access Management (IAM) system.
// Specifically:
//
// - The "secret:Read" operation allows listing and reading secrets.
// - The "secret:Execute" operation allows executing actions that use secrets.
// - The "secret:Write" operation allows setting and deleting secrets.
//
// Permissions may be granted for a specific secret or all secrets, within a
// tenant, or across all tenants.
//
// The builtin "admin" role grants all permissions including the above for the
// "default" tenant. The builtin "global-admin" role grants all permissions on
// all tenants. The builtin "user" role has "secret:Execute" permission
// for the "default" tenant.
//
// A secret name must start with an ASCII letter, which may be followed by
// ASCII letters, digits, '_', and '-'. A name may be at most 128 characters
// long. A name must not start with "ENGFLOW_".
//
// A secret value may contain any character except NUL ('\0'). A value may be
// at most 8192 characters long.
service Secret {
  // List returns a list of all secret names defined within a tenant, ordered
  // lexicographically by code point.
  //
  // List may return the following errors:
  //
  // - PERMISSION_DENIED: the caller does not have the "secret:Read" permission
  //   for all secrets.
  rpc List(ListRequest) returns (ListResponse) {}

  // Get retrieves the value of a specific secret.
  //
  // Get may return the following errors:
  //
  // - INVALID_ARGUMENT: name does not satisfy requirements
  // - PERMISSION_DENIED: the caller does not have the "secret:Read" permission
  //   for the requested secret.
  // - NOT_FOUND: the secret does not exist.
  rpc Get(GetRequest) returns (GetResponse) {}

  // Set creates a new secret or changes the value of an existing secret.
  //
  // Set may return the following errors:
  //
  // - INVALID_ARGUMENT: name or value does not satisfy requirements
  // - PERMISSION_DENIED: the caller does not have the "secret:Write"
  //   permission for the requested secret.
  rpc Set(SetRequest) returns (SetResponse) {}

  // Delete removes an existing secret.
  //
  // Delete may return the following errors:
  //
  // - INVALID_ARGUMENT: name does not satisfy requirements
  // - PERMISSION_DENIED: the caller does not have the "secret:Write"
  //   permission for the requested secret.
  // - FAILED_PRECONDITION: the secret does not exist.
  rpc Delete(DeleteRequest) returns (DeleteResponse) {}
}

message ListRequest {
  // Name of the EngFlow tenant.
  string instance_name = 1;

  // begin_index and end_index specify a range, limiting the results returned
  // by List. begin_index is inclusive, end_index is exclusive. If begin_index
  // is not set, it's effectively 0. If end_index is not set, it's effectively
  // the maximum length.
  int64 begin_index = 2;
  int64 end_index = 3;
}

message ListResponse {
  // List of secret names.
  repeated string name = 1;

  // Total number of secrets that could be returned by List, for use with with
  // begin_index and end_index for pagination.
  int64 count = 2;
}

message GetRequest {
  // Name of the EngFlow tenant.
  string instance_name = 1;

  // Name of the secret to retrieve.
  string name = 2;
}

message GetResponse {
  // Value of the secret.
  string value = 1;
}

message SetRequest {
  // Name of the EngFlow tenant.
  string instance_name = 1;

  // Name of the secret to create or update.
  string name = 2;

  // New value for the secret.
  string value = 3;
}

message SetResponse {}

message DeleteRequest {
  // Name of the EngFlow tenant.
  string instance_name = 1;

  // Name of the secret to remove.
  string name = 2;
}

message DeleteResponse {}