security

type Claims interface {
	// Get retrieves a claim by its key and returns its value as an interface{}.
	// The second return value indicates if the claim was found.
	Get(key string) (any, bool)
	// GetString retrieves a string claim by its key.
	GetString(key string) (string, bool)
	// GetInt64 retrieves an int64 claim by its key.
	GetInt64(key string) (int64, bool)
	// GetFloat64 retrieves a float64 claim by its key.
	GetFloat64(key string) (float64, bool)
	// GetBool retrieves a boolean claim by its key.
	GetBool(key string) (bool, bool)
	// GetStringSlice retrieves a string slice claim by its key.
	GetStringSlice(key string) ([]string, bool)
	// GetMap retrieves a map[string]any claim by its key.
	GetMap(key string) (map[string]any, bool)
	// UnmarshalValue unmarshals a claim with the given key into the provided Go type.
	// The target must be a pointer to a struct.
	UnmarshalValue(key string, target any) error
	// Export returns the raw claims data as a map of structpb.Value.
	Export() map[string]*structpb.Value
}

type Credential interface {
	// Type returns the type of the credential (e.g., "jwt", "apikey").
	Type() string

	// Raw returns the original, unparsed credential string.
	// For example, the full "Bearer eyJ..." JWT string, or the API key string.
	Raw() string

	// ParsedPayload unmarshals the credential's payload into the provided protobuf message.
	// This allows for type-safe unpacking of the payload into specific protobuf messages.
	ParsedPayload(message proto.Message) error

	// GetMeta returns the authentication-related metadata associated with the credential
	// as a standard Go map[string][]string, for easy consumption by Authenticator implementations.
	// This metadata is typically extracted and processed from the request context.
	GetMeta() map[string][]string

	// Source returns the canonical Protobuf representation of the credential.
	// This is essential for transmitting the credential data, for example, in a CredentialResponse.
	Source() *securityv1.CredentialSource
}

type CredentialResponse interface {
	// GetType returns the type of the credential.
	GetType() string

	// Payload returns the payload of the credential.
	// This should ideally return a structured type or a proto.Message.
	Payload() *securityv1.Payload

	// GetMeta returns the metadata associated with the credential response
	// as a standard Go map[string][]string, for easy consumption.
	GetMeta() map[string][]string

	// Response returns the canonical Protobuf representation of the credential response.
	// This allows direct access to the underlying protobuf message for serialization.
	Response() *securityv1.CredentialResponse
}

type Policy struct {
	ServiceMethod string // gRPC full method name, e.g., "/user.v1.UserService/GetUser"
	GatewayPath   string // HTTP path and method, e.g., "GET:/api/v1/users/{id}"
	Name          string // The policy name/definition string from the proto annotation, e.g., "admin-only"
	VersionID     string // A hash representing the version of this policy definition
}

type Principal interface {
	// GetID returns the unique identifier of the principal.
	GetID() string
	// GetDomain returns the domain associated with the principal.
	// This is often used in multi-tenant or multi-project environments.
	GetDomain() string
	// GetRoles returns a slice of roles assigned to the principal.
	GetRoles() []string
	// GetPermissions returns a slice of permissions granted to the principal.
	GetPermissions() []string
	// GetScopes returns a map of scopes associated with the principal.
	GetScopes() map[string]bool
	// GetClaims returns the custom claims associated with the principal.
	GetClaims() Claims
	// Export converts the Principal to its Protobuf representation.
	Export() *securityv1.Principal
}

type Request interface {
	// Kind returns the type of the request as a string (e.g., "grpc", "http").
	// This helps consumers understand how to interpret GetOperation(), GetMethod(), and GetRouteTemplate().
	Kind() string

	// GetOperation returns the primary identifier for the logical operation being performed.
	// The specific value depends on the Kind() and the nature of the request:
	// - For "grpc" kind: Returns the full gRPC method name (e.g., /package.Service/Method).
	// - For "http" kind:
	//   - If the HTTP request is a proxy for a gRPC method (e.g., via Kratos HTTP gateway),
	//     it returns the corresponding full gRPC method name.
	//   - Otherwise (for a pure HTTP service request), it returns the actual HTTP request path (e.g., /v1/users/123).
	// This value is typically used for policy lookup in `servicePolicies` (if it's a gRPC method name)
	// or for general operation identification.
	GetOperation() string

	// GetMethod returns the HTTP verb (e.g., "GET", "POST") if the request is an HTTP call.
	// For "grpc" kind requests, this method will return an empty string.
	GetMethod() string

	// GetRouteTemplate returns the matched HTTP route template (e.g., "/v1/users/{id}")
	// if the request is an HTTP call and a route template was matched.
	// This is typically used for policy lookup in `gatewayPolicies`.
	// For "grpc" kind requests, this method will return an empty string.
	GetRouteTemplate() string

	// Get returns the first value associated with the given key.
	// If the key is not found, it returns an empty string.
	Get(key string) string
	// Values returns the values associated with the given key.
	// It returns a slice of strings because sources like HTTP headers can have
	// multiple values for the same key.
	Values(key string) []string
	// GetAll returns all key-value pairs from the source.
	GetAll() map[string][]string
}

type SkipChecker func(ctx context.Context, req Request) bool