Documentation
¶
Overview ¶
Package firewall implements the Knowledge Firewall for P2P queries. Default policy is deny-all — explicit rules must be added to allow access.
Package firewall implements the Knowledge Firewall for P2P queries.
Index ¶
- Constants
- Variables
- func ValidateRule(rule ACLRule) error
- type ACLAction
- type ACLRule
- type AttestationResult
- type Firewall
- func (f *Firewall) AddRule(rule ACLRule) error
- func (f *Firewall) AttestResponse(responseHash, agentDIDHash []byte) (*AttestationResult, error)
- func (f *Firewall) FilterQuery(ctx context.Context, peerDID, toolName string) error
- func (f *Firewall) RemoveRule(peerDID string) int
- func (f *Firewall) Rules() []ACLRule
- func (f *Firewall) SanitizeResponse(response map[string]interface{}) map[string]interface{}
- func (f *Firewall) SetOwnerShield(shield *OwnerShield)
- func (f *Firewall) SetReputationChecker(fn ReputationChecker, minScore float64)
- func (f *Firewall) SetZKAttestFunc(fn ZKAttestFunc)
- type OwnerProtectionConfig
- type OwnerShield
- type ReputationChecker
- type ZKAttestFunc
Constants ¶
const WildcardAll = "*"
WildcardAll matches all peers or all tools.
Variables ¶
var ( ErrRateLimitExceeded = errors.New("rate limit exceeded") ErrGlobalRateLimitExceeded = errors.New("global rate limit exceeded") ErrQueryDenied = errors.New("query denied by firewall rule") ErrNoMatchingAllowRule = errors.New("query denied: no matching allow rule") )
Sentinel errors for firewall decisions.
Functions ¶
func ValidateRule ¶
ValidateRule checks whether an ACL rule is safe to add. It rejects overly permissive allow rules (wildcard peer + wildcard tools).
Types ¶
type ACLRule ¶
type ACLRule struct {
// PeerDID is the peer this rule applies to (WildcardAll for all peers).
PeerDID string `json:"peerDid"`
// Action is ACLActionAllow or ACLActionDeny.
Action ACLAction `json:"action"`
// Tools lists tool name patterns (supports * wildcard).
Tools []string `json:"tools"`
// RateLimit is max requests per minute (0 = unlimited).
RateLimit int `json:"rateLimit"`
}
ACLRule defines an access control rule.
type AttestationResult ¶
AttestationResult holds a structured ZK attestation proof from the prover.
type Firewall ¶
type Firewall struct {
// contains filtered or unexported fields
}
Firewall enforces access control and response sanitization for P2P queries.
func New ¶
func New(rules []ACLRule, logger *zap.SugaredLogger) *Firewall
New creates a new Firewall with deny-all default policy.
func (*Firewall) AddRule ¶
AddRule validates and adds a new ACL rule. Returns an error if the rule is overly permissive (e.g. allow * with all tools).
func (*Firewall) AttestResponse ¶
func (f *Firewall) AttestResponse(responseHash, agentDIDHash []byte) (*AttestationResult, error)
AttestResponse generates a ZK attestation proof for a response.
func (*Firewall) FilterQuery ¶
FilterQuery checks if a query from the given peer is allowed.
func (*Firewall) RemoveRule ¶
RemoveRule removes ACL rules matching the peer DID.
func (*Firewall) SanitizeResponse ¶
SanitizeResponse removes sensitive internal data from a response.
func (*Firewall) SetOwnerShield ¶
func (f *Firewall) SetOwnerShield(shield *OwnerShield)
SetOwnerShield sets the owner data protection shield.
func (*Firewall) SetReputationChecker ¶
func (f *Firewall) SetReputationChecker(fn ReputationChecker, minScore float64)
SetReputationChecker sets the reputation checker and minimum trust score.
func (*Firewall) SetZKAttestFunc ¶
func (f *Firewall) SetZKAttestFunc(fn ZKAttestFunc)
SetZKAttestFunc sets the ZK attestation function for response signing.
type OwnerProtectionConfig ¶
type OwnerProtectionConfig struct {
OwnerName string `json:"ownerName"`
OwnerEmail string `json:"ownerEmail"`
OwnerPhone string `json:"ownerPhone"`
ExtraTerms []string `json:"extraTerms,omitempty"`
BlockConversations bool `json:"blockConversations"`
}
OwnerProtectionConfig configures owner data protection.
type OwnerShield ¶
type OwnerShield struct {
// contains filtered or unexported fields
}
OwnerShield prevents owner personal data from leaking via P2P responses. No amount of USDC can bypass this layer.
func NewOwnerShield ¶
func NewOwnerShield(cfg OwnerProtectionConfig, logger *zap.SugaredLogger) *OwnerShield
NewOwnerShield creates a new OwnerShield from the given config.
func (*OwnerShield) ContainsOwnerData ¶
func (s *OwnerShield) ContainsOwnerData(text string) bool
ContainsOwnerData checks if the text contains any owner data.
func (*OwnerShield) ScanAndRedact ¶
func (s *OwnerShield) ScanAndRedact(response map[string]interface{}) (map[string]interface{}, []string)
ScanAndRedact recursively walks the response map and redacts owner data. It returns the redacted map and a list of redacted field paths.
type ReputationChecker ¶
ReputationChecker returns a trust score for a peer DID.
type ZKAttestFunc ¶
type ZKAttestFunc func(responseHash, agentDIDHash []byte) (*AttestationResult, error)
ZKAttestFunc generates a ZK attestation proof for a response.
Source Files