auth.go

package relay

import "context"

// -----------------------------------------------------------------------------
// Authorization Types
// -----------------------------------------------------------------------------

// AuthAction represents the type of action being authorized.
type AuthAction string

// Defined authorization actions.
const (
	AuthActionAgentRegister AuthAction = "agent:register"
	AuthActionSessionOpen   AuthAction = "session:open"
	AuthActionSessionTunnel AuthAction = "session:tunnel"
)

// AuthRequest is sent to the authorization endpoint to check if an operation
// is allowed. This follows a similar pattern to Docker Registry's token
// authentication service.
type AuthRequest struct {
	// Subject is the identity performing the action (user ID, token, or agent ID).
	Subject string `json:"subject"`

	// Action is the operation being performed (e.g., "agent:register", "session:open").
	Action AuthAction `json:"action"`

	// Resource is the target of the action (e.g., agent ID being accessed).
	Resource string `json:"resource"`

	// Context contains additional information about the request.
	Context map[string]string `json:"context,omitempty"`
}

// AuthResponse is returned by the authorization endpoint.
type AuthResponse struct {
	// Allowed indicates whether the action is permitted.
	Allowed bool `json:"allowed"`

	// Reason provides an explanation when the action is denied.
	Reason string `json:"reason,omitempty"`
}

// Authorizer defines the interface for authorization checks.
// Implementations can use webhooks, local policies, or other mechanisms.
type Authorizer interface {
	// Authorize checks if the requested action is allowed.
	// Returns an AuthResponse indicating whether the action is permitted.
	// If the authorizer is not configured or encounters an error, implementations
	// should define their fail-open or fail-closed behavior.
	Authorize(ctx context.Context, req *AuthRequest) (*AuthResponse, error)
}