policy

type Action string

type Decision struct {
	// Allowed is true if the tool call is permitted.
	Allowed bool
	// RuleID is the ID of the rule that produced this decision.
	RuleID string
	// Reason explains why the decision was made.
	Reason string

	// RequiresApproval is true when the matching rule has Action = ActionApprovalRequired.
	// When true, the tool call should be blocked pending human approval.
	RequiresApproval bool
	// ApprovalTimeout is the timeout duration from the rule (when RequiresApproval is true).
	ApprovalTimeout time.Duration
	// ApprovalTimeoutAction is the fallback action when approval times out.
	ApprovalTimeoutAction Action

	// RuleName is the human-readable name of the rule that produced this decision.
	RuleName string
	// HelpURL is a direct link to the rule in the Admin UI (e.g., "/admin/policies#rule-{ruleID}").
	HelpURL string
	// HelpText is a human explanation of how to resolve a denial
	// (e.g., "This tool is blocked. Ask an admin to modify the 'block-exec' rule.").
	HelpText string
}

type EvaluationContext struct {
	// ToolName is the name of the tool being invoked.
	ToolName string
	// ToolArguments are the arguments passed to the tool.
	ToolArguments map[string]interface{}
	// UserRoles are the roles assigned to the user making the request.
	UserRoles []string
	// SessionID is the current session identifier.
	SessionID string
	// IdentityID is the authenticated user's identity identifier.
	IdentityID string
	// IdentityName is the human-readable name of the identity.
	IdentityName string
	// RequestTime is when the tool call was received.
	RequestTime time.Time

	// Framework context (Phase 19)
	// Framework identifies which framework is in use ("crewai", "autogen", or "").
	Framework string
	// FrameworkAttrs contains framework-specific attributes for CEL evaluation.
	// Keys follow the pattern "crewai.role", "autogen.agent_type", etc.
	FrameworkAttrs map[string]string

	// Universal fields (populated from CanonicalAction)
	// ActionType is the canonical action type: "tool_call", "http_request", "command_exec", etc.
	ActionType string
	// ActionName is the universal action name (alias for ToolName).
	ActionName string
	// Protocol is the originating protocol: "mcp", "http", "websocket", "runtime".
	Protocol string
	// Gateway is the gateway that received the request: "mcp-gateway", "http-gateway", "runtime".
	Gateway string

	// Destination fields
	// DestURL is the full destination URL for outbound requests.
	DestURL string
	// DestDomain is the destination domain name.
	DestDomain string
	// DestIP is the destination IP address.
	DestIP string
	// DestPort is the destination port number.
	DestPort int
	// DestScheme is the destination URL scheme (http, https, ws, wss).
	DestScheme string
	// DestPath is the destination URL path.
	DestPath string
	// DestCommand is the command being executed (for command_exec actions).
	DestCommand string
}

type Policy struct {
	// ID is the unique identifier for this policy.
	ID string
	// Name is the human-readable name for this policy.
	Name string
	// Description provides additional context about the policy.
	Description string
	// Priority determines policy evaluation order (lower = higher priority).
	Priority int
	// Rules are the authorization rules in this policy.
	Rules []Rule
	// Enabled indicates if this policy is active.
	Enabled bool
	// CreatedAt is when the policy was created (UTC).
	CreatedAt time.Time
	// UpdatedAt is when the policy was last modified (UTC).
	UpdatedAt time.Time
}

type PolicyEngine interface {
	// Evaluate evaluates a tool call against loaded policies.
	// Returns Decision with Allowed=true/false and reason.
	Evaluate(ctx context.Context, evalCtx EvaluationContext) (Decision, error)
}

type PolicyStore interface {
	// GetAllPolicies returns all enabled policies.
	GetAllPolicies(ctx context.Context) ([]Policy, error)
	// GetPolicy returns a policy by ID.
	GetPolicy(ctx context.Context, id string) (*Policy, error)
	// SavePolicy creates or updates a policy.
	SavePolicy(ctx context.Context, p *Policy) error
	// DeletePolicy removes a policy by ID.
	DeletePolicy(ctx context.Context, id string) error
	// GetPolicyWithRules returns a policy with all its rules loaded.
	GetPolicyWithRules(ctx context.Context, id string) (*Policy, error)
	// SaveRule creates or updates a rule within a policy.
	SaveRule(ctx context.Context, policyID string, r *Rule) error
	// DeleteRule removes a rule by ID.
	DeleteRule(ctx context.Context, policyID, ruleID string) error
}

type Rule struct {
	// ID is the unique identifier for this rule.
	ID string
	// Name is a human-readable name for this rule.
	Name string
	// Priority determines rule evaluation order (lower = higher priority).
	Priority int
	// ToolMatch is a glob pattern to match tool names (e.g., "file_*").
	ToolMatch string
	// Condition is a CEL expression that must evaluate to true for the rule to apply.
	Condition string
	// Action is the result when this rule matches and condition is true.
	Action Action
	// CreatedAt is when the rule was created (UTC).
	CreatedAt time.Time

	// ApprovalTimeout is how long to wait for approval when Action is ActionApprovalRequired.
	// Defaults to 5 minutes if not specified.
	ApprovalTimeout time.Duration
	// TimeoutAction specifies what to do when an approval request times out.
	// Must be ActionDeny (default) or ActionAllow.
	TimeoutAction Action

	// HelpText is optional admin-provided guidance shown when this rule denies an action.
	// When empty, a default help text is generated from the rule name.
	HelpText string
}