authz

type Authorizer interface {
	// Authorized individual rule specifications are checked.
	Authorized(ctx context.Context, p security.Principal, spec RuleSpec) (bool, error)
}

type Factory interface {
	NewAuthorizer(config *authzv1.Authorizer, opts ...options.Option) (Authorizer, error)
}

type FactoryFunc func(config *authzv1.Authorizer, opts ...options.Option) (Authorizer, error)

type FilterQuerier interface {
	// FilterAuthorized is the generic and powerful core method of this interface.
	// It filters a list of RuleSpecs and returns the subset for which the principal is authorized.
	// It is useful for complex, non-standard batch filtering scenarios.
	FilterAuthorized(ctx context.Context, p security.Principal, specs []RuleSpec) ([]RuleSpec, error)

	// FilterAuthorizedResources is a convenience method for the common use case of filtering a list of resource IDs.
	// It abstracts away the complexity of creating and parsing RuleSpecs.
	// The specTemplate provides a template for the check, where its Resource field is ignored.
	FilterAuthorizedResources(ctx context.Context, p security.Principal, specTemplate RuleSpec, resources []string) ([]string, error)

	// FilterAuthorizedActions is a convenience method to determine which actions a principal can perform on a given resource.
	// The specTemplate provides a template for the check, where its Action field is ignored.
	FilterAuthorizedActions(ctx context.Context, p security.Principal, specTemplate RuleSpec, actions []string) ([]string, error)

	// FilterAuthorizedDomains is a convenience method to determine which domains a principal has access to.
	// The specTemplate provides a template for the check, where its Domain field is ignored.
	FilterAuthorizedDomains(ctx context.Context, p security.Principal, specTemplate RuleSpec, domains []string) ([]string, error)
}

type PolicyModifier interface {

	// AddUserRole assigns a role to a user.
	// Returns true if the assignment was added, false if it already existed.
	AddUserRole(ctx context.Context, userID string, roleID string) (bool, error)
	// RemoveUserRole revokes a role from a user.
	// Returns true if the assignment was removed, false if it didn't exist.
	RemoveUserRole(ctx context.Context, userID string, roleID string) (bool, error)
	// RemoveAllUserRoles removes all roles assigned to a specific user.
	// Returns true if any assignments were removed.
	RemoveAllUserRoles(ctx context.Context, userID string) (bool, error)

	// AddRolePermission grants a specific permission to a role.
	// The permission is defined by the RuleSpec (resource and action).
	// Returns true if the permission was added, false if it already existed.
	AddRolePermission(ctx context.Context, roleID string, spec RuleSpec) (bool, error)
	// RemoveRolePermission revokes a specific permission from a role.
	// Returns true if the permission was removed, false if it didn't exist.
	RemoveRolePermission(ctx context.Context, roleID string, spec RuleSpec) (bool, error)
	// RemoveAllRolePermissions removes all permissions granted to a specific role.
	// Returns true if any permissions were removed.
	RemoveAllRolePermissions(ctx context.Context, roleID string) (bool, error)

	// AddUserPermission grants a specific permission directly to a user (less common in pure RBAC, but useful for ABAC or exceptions).
	// Returns true if the permission was added, false if it already existed.
	AddUserPermission(ctx context.Context, userID string, spec RuleSpec) (bool, error)
	// RemoveUserPermission revokes a specific permission directly from a user.
	// Returns true if the permission was removed, false if it didn't exist.
	RemoveUserPermission(ctx context.Context, userID string, spec RuleSpec) (bool, error)
	// RemoveAllUserPermissions removes all direct permissions granted to a specific user.
	// Returns true if any permissions were removed.
	RemoveAllUserPermissions(ctx context.Context, userID string) (bool, error)
}

type Reloader interface {
	// Reload triggers a reload of the authorization policies from the underlying storage.
	Reload() error
}

type RuleSpec struct {
	Domain   string // Represent the project or tenant. It can be empty.
	Resource string // The resource being accessed.
	Action   string // Actions to be performed on the resource.
	// Attributes contain additional attributes related to this rule, such as the owner of the resource, status, and so on.
	// This allows RuleSpec to carry more complex contextual information to support ABAC.
	Attributes security.Claims
}