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 ¶
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 ¶
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.
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 multiple policy script runners. It manages the lifecycle of policy scripts, handles communication with them, and provides resilient operation with automatic restart capabilities. Each unique script path gets its own ScriptRunner instance.
func (*PolicyManager) GetScriptPath ¶ added in v0.20.3
func (pm *PolicyManager) GetScriptPath() string
GetScriptPath returns the default script path.
func (*PolicyManager) IsEnabled ¶
func (pm *PolicyManager) IsEnabled() bool
IsEnabled returns whether the policy manager is enabled.
func (*PolicyManager) IsRunning ¶
func (pm *PolicyManager) IsRunning() bool
IsRunning returns whether the default policy script is currently running. Deprecated: Use getOrCreateRunner(scriptPath).IsRunning() for specific scripts.
func (*PolicyManager) Shutdown ¶
func (pm *PolicyManager) Shutdown()
Shutdown gracefully shuts down the policy manager and all running scripts.
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.
type ScriptRunner ¶ added in v0.27.1
type ScriptRunner struct {
// contains filtered or unexported fields
}
ScriptRunner manages a single policy script process. Each unique script path gets its own independent runner with its own goroutine.
func (*ScriptRunner) IsRunning ¶ added in v0.27.1
func (sr *ScriptRunner) IsRunning() bool
IsRunning returns whether the script is currently running.
func (*ScriptRunner) ProcessEvent ¶ added in v0.27.1
func (sr *ScriptRunner) ProcessEvent(evt *PolicyEvent) (*PolicyResponse, error)
ProcessEvent sends an event to the script and waits for a response.
func (*ScriptRunner) Start ¶ added in v0.27.1
func (sr *ScriptRunner) Start() error
Start starts the script process.
func (*ScriptRunner) Stop ¶ added in v0.27.1
func (sr *ScriptRunner) Stop() error
Stop stops the script gracefully.
Source Files
¶
- policy.go