policy

package
v0.26.4 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 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 whitelist and blacklist policies for event kinds. Whitelist takes precedence over blacklist - if whitelist is present, only whitelisted kinds are allowed. If only blacklist is present, all kinds except blacklisted ones are allowed.

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"`
	// DefaultPolicy determines the default behavior when no rules deny an event ("allow" or "deny", defaults to "allow")
	DefaultPolicy string `json:"default_policy"`
	// Manager handles policy script execution
	Manager *PolicyManager `json:"-"`
}

P represents a complete policy configuration for a Nostr relay. It defines access control rules, kind filtering, and default behavior. Policies are evaluated in order: global rules, kind filtering, specific rules, then default policy.

func New

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

New creates a new policy from JSON configuration. If policyJSON is empty, returns a policy with default settings. The default_policy field defaults to "allow" if not specified.

func NewWithManager

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

NewWithManager creates a new policy with a policy manager for script execution. It initializes the policy manager, loads configuration from files, and starts background processes for script management and periodic health checks.

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 based on the policy configuration. The access parameter should be "write" for accepting events or "read" for filtering events. Returns true if the event is allowed, false if denied, and an error if validation fails. Policy evaluation order: global rules → kind filtering → specific rules → default policy.

func (*P) LoadFromFile

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

LoadFromFile loads policy configuration from a JSON file. Returns an error if the file doesn't exist, can't be read, or contains invalid JSON.

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. It embeds the Nostr event and adds authentication and network context.

func (*PolicyEvent) MarshalJSON

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

MarshalJSON implements custom JSON marshaling for PolicyEvent. It safely serializes the embedded event and additional context fields.

type PolicyManager

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

PolicyManager handles policy script execution and management. It manages the lifecycle of policy scripts, handles communication with them, and provides resilient operation with automatic restart capabilities.

func (*PolicyManager) GetScriptPath added in v0.20.3

func (pm *PolicyManager) GetScriptPath() string

GetScriptPath returns the path to the policy script.

func (*PolicyManager) IsEnabled

func (pm *PolicyManager) IsEnabled() bool

IsEnabled returns whether the policy manager is enabled. This is set during initialization and doesn't change during runtime.

func (*PolicyManager) IsRunning

func (pm *PolicyManager) IsRunning() bool

IsRunning returns whether the policy script is currently running. This can change during runtime as scripts start, stop, or crash.

func (*PolicyManager) ProcessEvent

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

ProcessEvent sends an event to the policy script and waits for a response. Returns the script's decision or an error if the script is not running or communication fails.

func (*PolicyManager) Shutdown

func (pm *PolicyManager) Shutdown()

Shutdown gracefully shuts down the policy manager. It cancels the context and stops any running policy script.

func (*PolicyManager) StartPolicy

func (pm *PolicyManager) StartPolicy() error

StartPolicy starts the policy script process. Returns an error if the script doesn't exist, can't be executed, or is already running.

func (*PolicyManager) StopPolicy

func (pm *PolicyManager) StopPolicy() error

StopPolicy stops the policy script gracefully with SIGTERM, falling back to SIGKILL if needed. Returns an error if the policy is not currently running.

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. The script should return JSON with these fields to indicate its decision.

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 defines policy criteria for a specific event kind.

Rules are evaluated in the following order: 1. If Script is present and running, it determines the outcome 2. If Script fails or is not running, falls back to default_policy 3. Otherwise, all specified criteria are evaluated as AND operations

For pubkey allow/deny lists: whitelist takes precedence over blacklist. If whitelist has entries, only whitelisted pubkeys are allowed. If only blacklist has entries, all pubkeys except blacklisted ones are allowed.

Source Files

  • policy.go

Jump to

Keyboard shortcuts

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