security

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Mar 11, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// MaxMessageSize is the hard limit for message payload size (1 MB).
	MaxMessageSize = 1 << 20

	// NonceWindowDuration is how long nonces are remembered for replay protection.
	NonceWindowDuration = 5 * time.Minute

	// TimestampSkew is the maximum allowed clock difference.
	TimestampSkew = 2 * time.Minute
)
View Source
const DefaultExecTimeout = 30 * time.Second

DefaultExecTimeout is the default timeout for sandbox command execution.

View Source
const DefaultTOFUExpiry = 30 * 24 * time.Hour // 30 days

DefaultTOFUExpiry is the default duration after which a TOFU trust entry expires.

View Source
const MinTrustForGossip = TrustVerified

MinTrustForGossip is the minimum trust level required to accept gossip from a peer.

View Source
const NostrReputationKind = 30078

NostrReputationKind is the Nostr event kind for reputation claims (NIP-78 application-specific data).

View Source
const SecondHandReputationWeight = 0.3

SecondHandReputationWeight is the weight applied to reputation claims from other peers.

Variables

This section is empty.

Functions

func MarshalClaim

func MarshalClaim(claim *ReputationClaim) ([]byte, error)

MarshalClaim serializes a claim to JSON for Nostr event content.

func TrustLevelString

func TrustLevelString(level TrustLevel) string

TrustLevelString returns a human-readable name for a TrustLevel.

Types

type BehaviorType

type BehaviorType string

BehaviorType represents the type of observed behavior from a peer.

const (
	BehaviorSuccess           BehaviorType = "success"
	BehaviorTimeout           BehaviorType = "timeout"
	BehaviorError             BehaviorType = "error"
	BehaviorInvalidSignature  BehaviorType = "invalid_signature"
	BehaviorSpam              BehaviorType = "spam"
	BehaviorProtocolViolation BehaviorType = "protocol_violation"
)

type MessageValidator

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

MessageValidator provides message-level security: signature verification, replay protection via nonces, and size limits.

func NewMessageValidator

func NewMessageValidator() *MessageValidator

NewMessageValidator creates a new message validator.

func (*MessageValidator) CleanExpiredNonces

func (v *MessageValidator) CleanExpiredNonces()

CleanExpiredNonces removes nonces older than the window duration.

func (*MessageValidator) ValidateMessage

func (v *MessageValidator) ValidateMessage(env *envelope.Envelope, pubKeyStr string) error

ValidateMessage validates the integrity and freshness of an envelope.

type ReputationClaim

type ReputationClaim struct {
	Issuer    string    `json:"issuer"`  // pubkey of the issuer
	Subject   string    `json:"subject"` // pubkey of the rated peer
	Score     float64   `json:"score"`   // 0.0 - 1.0
	Reason    string    `json:"reason"`  // brief description
	Timestamp time.Time `json:"timestamp"`
}

ReputationClaim represents a reputation assertion published via Nostr.

func UnmarshalClaim

func UnmarshalClaim(data []byte) (*ReputationClaim, error)

UnmarshalClaim deserializes a claim from JSON.

type ReputationEntry

type ReputationEntry struct {
	PubKey      string    `json:"pub_key"`
	Score       float64   `json:"score"`
	EventCount  int64     `json:"event_count"`
	LastUpdated time.Time `json:"last_updated"`
}

ReputationEntry tracks the reputation of a single peer.

type ReputationGossip

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

ReputationGossip manages publishing and consuming reputation claims via Nostr.

func NewReputationGossip

func NewReputationGossip(store *ReputationStore, trustStore *TrustStore, selfPubKey string) *ReputationGossip

NewReputationGossip creates a new gossip manager.

func (*ReputationGossip) CreateClaim

func (rg *ReputationGossip) CreateClaim(subjectPubKey string) *ReputationClaim

CreateClaim creates a reputation claim for publishing.

func (*ReputationGossip) ProcessClaim

func (rg *ReputationGossip) ProcessClaim(claim *ReputationClaim) bool

ProcessClaim processes an incoming reputation claim from another peer. It only accepts claims from peers with TrustVerified or higher, and applies SecondHandReputationWeight to the score.

type ReputationStore

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

ReputationStore tracks per-peer reputation scores using EWMA.

func NewReputationStore

func NewReputationStore() *ReputationStore

NewReputationStore creates a new reputation store with default settings.

func (*ReputationStore) GetEntry

func (rs *ReputationStore) GetEntry(pubKey string) *ReputationEntry

GetEntry returns the full reputation entry for a peer, or nil if not found.

func (*ReputationStore) GetScore

func (rs *ReputationStore) GetScore(pubKey string) float64

GetScore returns the reputation score for a peer. Returns 0.5 (neutral) if unknown.

func (*ReputationStore) IsMalicious

func (rs *ReputationStore) IsMalicious(pubKey string) bool

IsMalicious returns true if the peer's reputation is below the malicious threshold.

func (*ReputationStore) ListEntries

func (rs *ReputationStore) ListEntries() []ReputationEntry

ListEntries returns all reputation entries.

func (*ReputationStore) LoadFromFile

func (rs *ReputationStore) LoadFromFile(path string) error

LoadFromFile loads the reputation store from a JSON file.

func (*ReputationStore) RecordEvent

func (rs *ReputationStore) RecordEvent(pubKey string, behavior BehaviorType)

RecordEvent records a behavior event for a peer and updates the EWMA score.

func (*ReputationStore) SaveToFile

func (rs *ReputationStore) SaveToFile(path string) error

SaveToFile persists the reputation store to a JSON file.

func (*ReputationStore) SetScore

func (rs *ReputationStore) SetScore(pubKey string, score float64)

SetScore sets the reputation score for a peer in a thread-safe manner. This is the safe way to update scores from external sources (e.g., gossip).

type Sandbox

type Sandbox interface {
	// Execute runs a command within the sandbox constraints.
	Execute(ctx context.Context, command string, args []string) ([]byte, error)
}

Sandbox defines the execution-level security interface. It restricts what tools/commands an agent can invoke.

type SessionKey

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

SessionKey holds the derived symmetric key for encrypting messages between two peers.

func DeriveSessionKey

func DeriveSessionKey(privateKey *ecdh.PrivateKey, peerPublicKey *ecdh.PublicKey, peerID string) (*SessionKey, error)

DeriveSessionKey computes a shared secret via X25519 ECDH and derives a 32-byte symmetric key using HKDF-SHA256. The info parameter provides context binding (e.g., "peerclaw-session-v1").

func NewSessionKeyFromBytes

func NewSessionKeyFromBytes(key []byte, peerID string) (*SessionKey, error)

NewSessionKeyFromBytes creates a SessionKey from raw key bytes. Used primarily for testing.

func (*SessionKey) Decrypt

func (sk *SessionKey) Decrypt(data []byte) ([]byte, error)

Decrypt decrypts data produced by Encrypt. Expects input format: nonce (24 bytes) || ciphertext || tag (16 bytes).

func (*SessionKey) Encrypt

func (sk *SessionKey) Encrypt(plaintext []byte) ([]byte, error)

Encrypt encrypts plaintext using XChaCha20-Poly1305 with a random nonce. The nonce is prepended to the ciphertext. Returns: nonce (24 bytes) || ciphertext || tag (16 bytes).

func (*SessionKey) PeerID

func (sk *SessionKey) PeerID() string

PeerID returns the remote peer identifier associated with this session key.

type TrustChangeCallback

type TrustChangeCallback func(pubKey string, oldLevel, newLevel TrustLevel)

TrustChangeCallback is called when a trust entry changes.

type TrustEntry

type TrustEntry struct {
	PublicKey string     `json:"public_key"`
	Level     TrustLevel `json:"level"`
	FirstSeen string     `json:"first_seen"`
	LastSeen  string     `json:"last_seen,omitempty"`
	Alias     string     `json:"alias,omitempty"`
	ExpiresAt time.Time  `json:"expires_at,omitempty"`
}

TrustEntry records trust information about a peer.

type TrustLevel

type TrustLevel int

TrustLevel represents how much an agent is trusted.

const (
	TrustUnknown  TrustLevel = 0
	TrustTOFU     TrustLevel = 1 // Trust On First Use
	TrustVerified TrustLevel = 2 // Explicitly verified
	TrustBlocked  TrustLevel = 3 // Explicitly blocked
	TrustPinned   TrustLevel = 4 // Permanently pinned (highest trust)
)

type TrustStore

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

TrustStore manages TOFU trust relationships with peers.

func NewTrustStore

func NewTrustStore() *TrustStore

NewTrustStore creates a new empty trust store.

func (*TrustStore) Check

func (ts *TrustStore) Check(pubKey string) TrustLevel

Check returns the trust level for a public key. If the entry is a TOFU entry that has expired, TrustUnknown is returned.

func (*TrustStore) CleanExpired

func (ts *TrustStore) CleanExpired()

CleanExpired removes expired TOFU entries from the store. Only TOFU entries are subject to expiration; entries at TrustVerified or higher (including TrustBlocked and TrustPinned) are never removed.

func (*TrustStore) Export

func (ts *TrustStore) Export() ([]byte, error)

Export serializes all entries to JSON bytes.

func (*TrustStore) Import

func (ts *TrustStore) Import(data []byte) error

Import merges entries from JSON bytes into the store. Existing entries are overwritten by imported entries with the same key.

func (*TrustStore) IsAllowed

func (ts *TrustStore) IsAllowed(pubKey string) bool

IsAllowed returns true if the peer is trusted (TOFU, Verified, or Pinned).

func (*TrustStore) IsAllowedWithReputation

func (ts *TrustStore) IsAllowedWithReputation(pubKey string) bool

IsAllowedWithReputation returns true if the peer passes both trust and reputation checks. If no ReputationStore is set, it falls back to IsAllowed.

func (*TrustStore) ListEntries

func (ts *TrustStore) ListEntries() []TrustEntry

ListEntries returns all trust entries sorted by public key.

func (*TrustStore) LoadFromFile

func (ts *TrustStore) LoadFromFile(path string) error

LoadFromFile loads the trust store from a JSON file.

func (*TrustStore) OnTrustChange

func (ts *TrustStore) OnTrustChange(cb TrustChangeCallback)

OnTrustChange registers a callback invoked when trust levels change.

func (*TrustStore) RemoveEntry

func (ts *TrustStore) RemoveEntry(pubKey string) bool

RemoveEntry removes a trust entry entirely.

func (*TrustStore) SaveToFile

func (ts *TrustStore) SaveToFile(path string) error

SaveToFile persists the trust store to a JSON file.

func (*TrustStore) SetAlias

func (ts *TrustStore) SetAlias(pubKey, alias string)

SetAlias sets a human-readable alias for a peer.

func (*TrustStore) SetReputationStore

func (ts *TrustStore) SetReputationStore(rs *ReputationStore)

SetReputationStore associates a ReputationStore with this TrustStore.

func (*TrustStore) SetTrust

func (ts *TrustStore) SetTrust(pubKey string, level TrustLevel)

SetTrust explicitly sets the trust level for a public key.

func (*TrustStore) TouchLastSeen

func (ts *TrustStore) TouchLastSeen(pubKey string)

TouchLastSeen updates the LastSeen timestamp for a peer.

func (*TrustStore) TrustOnFirstUse

func (ts *TrustStore) TrustOnFirstUse(pubKey, firstSeen string) TrustLevel

TrustOnFirstUse records a new peer with TOFU trust if not already known. The TOFU entry expires after DefaultTOFUExpiry (30 days). Returns the trust level (existing or newly created).

type WhitelistSandbox

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

WhitelistSandbox only allows execution of commands in the whitelist.

func NewWhitelistSandbox

func NewWhitelistSandbox(tools []string) *WhitelistSandbox

NewWhitelistSandbox creates a sandbox that only permits the given tool names.

func (*WhitelistSandbox) Execute

func (s *WhitelistSandbox) Execute(ctx context.Context, command string, args []string) ([]byte, error)

Execute runs a command if it's in the whitelist using exec.CommandContext.

func (*WhitelistSandbox) IsAllowed

func (s *WhitelistSandbox) IsAllowed(command string) bool

IsAllowed checks if a command is permitted.

func (*WhitelistSandbox) SetTimeout

func (s *WhitelistSandbox) SetTimeout(d time.Duration)

SetTimeout sets the execution timeout for sandbox commands.

Jump to

Keyboard shortcuts

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