syntax = "proto3";

package tars.auth.v1;

import "google/protobuf/descriptor.proto";

// AuthType defines the type of authentication mechanism.
enum AuthType {
  AUTH_TYPE_UNSPECIFIED = 0;
  AUTH_TYPE_API_KEY = 1;
  AUTH_TYPE_SERVICE_ACCOUNT = 2;
  AUTH_TYPE_USER_TOKEN = 3;
}

// AuthOptions defines authentication requirements for an RPC method.
// If this annotation is not present on a method, the method is public (no auth required).
// If present with empty auth_types, any valid authentication is accepted.
// If present with auth_types specified, only those auth types are accepted.
message AuthOptions {
  // The types of authentication accepted for this method.
  // If empty, any valid authentication is accepted.
  // If specified, only the listed authentication types are accepted.
  repeated AuthType auth_types = 1;

  // Additional scopes or permissions required. The caller must satisfy ALL
  // listed scopes.
  //
  // Persona ladder (admin > project_owner > user):
  //   - "admin": platform admins (authn.user.role in admin/super_admin).
  //     Satisfies every lower tier as well.
  //   - "project_owner": the owner of the project the request targets, i.e. a
  //     user with project_members.role = "admin" on that project. This is NOT
  //     a static claim scope -- the interceptor resolves it per-request by
  //     extracting the target (customer_id, project_id) from the message (see
  //     project_id_field / customer_id_field below) and checking membership.
  //     A platform "admin" also satisfies it.
  //   - "read"/"write": any authenticated caller (the "user" tier).
  // Examples: "admin", "project_owner", "read", "write"
  repeated string scopes = 2;
}

// Method-level extension for authentication requirements.
extend google.protobuf.MethodOptions {
  AuthOptions auth = 50001;
}

// Field-level overrides for resource-aware "project_owner" enforcement. By
// convention the interceptor reads message fields named "customer_id" and
// "project_id" to identify the targeted project. Set these options to point
// the interceptor at differently-named fields. At most one field per message
// should carry each option.
extend google.protobuf.FieldOptions {
  // Marks the field that holds the target project id.
  bool project_id_field = 50007;
  // Marks the field that holds the target customer id.
  bool customer_id_field = 50008;
}
