policy

package
v0.17.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2025 License: Unlicense Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Kinds

type Kinds struct {
	// Whitelist is a list of event kinds that are allowed to be written to the relay. If any are present, implicitly all others are denied.
	Whitelist []int `json:"whitelist,omitempty"`
	// Blacklist is a list of event kinds that are not allowed to be written to the relay. If any are present, implicitly all others are allowed. Only takes effect in the absence of a Whitelist.
	Blacklist []int `json:"blacklist,omitempty"`
}

Kinds defines the filter for events by kind; the whitelist overrides the blacklist if it has any fields, and the blacklist is ignored (implicitly all not-whitelisted are blacklisted)

type P

type P struct {
	// Kind is policies for accepting or rejecting events by kind number.
	Kind Kinds `json:"kind"`
	// Rules is a map of rules for criteria that must be met for the event to be allowed to be written to the relay.
	Rules map[int]Rule `json:"rules"`
	// Global is a rule set that applies to all events.
	Global Rule `json:"global"`
	// Manager handles policy script execution
	Manager *PolicyManager `json:"-"`
}

P is a policy for a relay's ACL.

func New

func New(policyJSON []byte) (p *P, err error)

New creates a new policy from JSON configuration

func NewWithManager

func NewWithManager(ctx context.Context, appName string, enabled bool) *P

NewWithManager creates a new policy with a policy manager for script execution

func (*P) CheckPolicy

func (p *P) CheckPolicy(access string, ev *event.E, loggedInPubkey []byte, ipAddress string) (allowed bool, err error)

CheckPolicy checks if an event is allowed to be written to the relay based on the policy. The access parameter is either "write" or "read", write is for accepting events and read is for filtering events to send back to the client.

func (*P) LoadFromFile

func (p *P) LoadFromFile(configPath string) error

LoadFromFile loads policy configuration from a JSON file

type PolicyEvent

type PolicyEvent struct {
	*event.E
	LoggedInPubkey string `json:"logged_in_pubkey,omitempty"`
	IPAddress      string `json:"ip_address,omitempty"`
}

PolicyEvent represents an event with additional context for policy scripts

func (*PolicyEvent) MarshalJSON

func (pe *PolicyEvent) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling for PolicyEvent

type PolicyManager

type PolicyManager struct {
	// contains filtered or unexported fields
}

PolicyManager handles policy script execution and management

func (*PolicyManager) IsDisabled

func (pm *PolicyManager) IsDisabled() bool

IsDisabled returns whether policy is disabled due to failure

func (*PolicyManager) IsEnabled

func (pm *PolicyManager) IsEnabled() bool

IsEnabled returns whether policy is enabled

func (*PolicyManager) IsRunning

func (pm *PolicyManager) IsRunning() bool

IsRunning returns whether policy is currently running

func (*PolicyManager) ProcessEvent

func (pm *PolicyManager) ProcessEvent(evt *PolicyEvent) (*PolicyResponse, error)

ProcessEvent sends an event to the policy script and waits for a response

func (*PolicyManager) Shutdown

func (pm *PolicyManager) Shutdown()

Shutdown gracefully shuts down the policy manager

func (*PolicyManager) StartPolicy

func (pm *PolicyManager) StartPolicy() error

StartPolicy starts the policy script

func (*PolicyManager) StopPolicy

func (pm *PolicyManager) StopPolicy() error

StopPolicy stops the policy script gracefully, with SIGKILL fallback

type PolicyResponse

type PolicyResponse struct {
	ID     string `json:"id"`
	Action string `json:"action"` // accept, reject, or shadowReject
	Msg    string `json:"msg"`    // NIP-20 response message (only used for reject)
}

PolicyResponse represents a response from the policy script

type Rule

type Rule struct {
	// Description is a human-readable description of the rule.
	Description string `json:"description"`
	// Script is a path to a script that will be used to determine if the event should be allowed to be written to the relay. The script should be a standard bash script or whatever is native to the platform. The script will return its opinion to be one of the criteria that must be met for the event to be allowed to be written to the relay (AND).
	Script string `json:"script,omitempty"`
	// WriteAllow is a list of pubkeys that are allowed to write this event kind to the relay. If any are present, implicitly all others are denied.
	WriteAllow []string `json:"write_allow,omitempty"`
	// WriteDeny is a list of pubkeys that are not allowed to write this event kind to the relay. If any are present, implicitly all others are allowed. Only takes effect in the absence of a WriteAllow.
	WriteDeny []string `json:"write_deny,omitempty"`
	// ReadAllow is a list of pubkeys that are allowed to read this event kind from the relay. If any are present, implicitly all others are denied.
	ReadAllow []string `json:"read_allow,omitempty"`
	// ReadDeny is a list of pubkeys that are not allowed to read this event kind from the relay. If any are present, implicitly all others are allowed. Only takes effect in the absence of a ReadAllow.
	ReadDeny []string `json:"read_deny,omitempty"`
	// MaxExpiry is the maximum expiry time in seconds for events written to the relay. If 0, there is no maximum expiry. Events must have an expiry time if this is set, and it must be no more than this value in the future compared to the event's created_at time.
	MaxExpiry *int64 `json:"max_expiry,omitempty"`
	// MustHaveTags is a list of tag key letters that must be present on the event for it to be allowed to be written to the relay.
	MustHaveTags []string `json:"must_have_tags,omitempty"`
	// SizeLimit is the maximum size in bytes for the event's total serialized size.
	SizeLimit *int64 `json:"size_limit,omitempty"`
	// ContentLimit is the maximum size in bytes for the event's content field.
	ContentLimit *int64 `json:"content_limit,omitempty"`
	// Privileged means that this event is either authored by the authenticated pubkey, or has a p tag that contains the authenticated pubkey. This type of event is only sent to users who are authenticated and are party to the event.
	Privileged bool `json:"privileged,omitempty"`
	// RateLimit is the amount of data can be written to the relay per second by the authenticated pubkey. If 0, there is no rate limit. This is applied via the use of an EWMA of the event publication history on the authenticated connection
	RateLimit *int64 `json:"rate_limit,omitempty"`
	// MaxAgeOfEvent is the offset in seconds that is the oldest timestamp allowed for an event's created_at time. If 0, there is no maximum age. Events must have a created_at time if this is set, and it must be no more than this value in the past compared to the current time.
	MaxAgeOfEvent *int64 `json:"max_age_of_event,omitempty"`
	// MaxAgeEventInFuture is the offset in seconds that is the newest timestamp allowed for an event's created_at time ahead of the current time.
	MaxAgeEventInFuture *int64 `json:"max_age_event_in_future,omitempty"`
}

Rule is a rule for an event kind.

If Script is present, it overrides all other criteria.

The criteria have mutual exclude semantics on pubkey white/blacklists, if whitelist has any fields, blacklist is ignored (implicitly all not-whitelisted are blacklisted).

The other criteria are evaluated as AND operations, everything specified must match for the event to be allowed to be written to the relay.

Source Files

  • policy.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL