firewall

Documentation

Overview

Package firewall implements the Retrieval Firewall: policy-governed access control at the retrieval level using sensitivity labels, classification tiers, blocked-label enforcement, and namespace isolation.

The firewall operates on metadata only — no content inspection. It is deterministic, fast, and auditable.

Reference: Tech Spec Addendum Sections A3.1, A3.4, A3.5, A3.6, A3.7, A3.8.

Index

• type FilterResult
• type PreQueryDenial
  • func (d *PreQueryDenial) Error() string
• type RetrievalFirewall
  • func New(cfg config.DaemonRetrievalFirewallConfig, logger *slog.Logger) *RetrievalFirewall
  • func (fw *RetrievalFirewall) Enabled() bool
  • func (fw *RetrievalFirewall) PostFilter(src *config.Source, records []destination.TranslatedPayload) FilterResult
  • func (fw *RetrievalFirewall) PreQuery(src *config.Source, namespace string) *PreQueryDenial
  • func (fw *RetrievalFirewall) TierIndex(tier string) int
  • func (fw *RetrievalFirewall) WithMetrics(filteredTotal *prometheus.CounterVec, deniedTotal *prometheus.CounterVec, ...) *RetrievalFirewall

Types

type FilterResult

type FilterResult struct {
	// Records is the filtered set of memories visible to the source.
	Records []destination.TranslatedPayload
	// Filtered is true when at least one memory was removed.
	Filtered bool
	// FilteredLabels is the set of sensitivity labels that caused removals.
	FilteredLabels []string
	// TierFiltered is true when at least one memory was removed due to tier.
	TierFiltered bool
	// CountRemoved is the number of memories removed by the firewall.
	CountRemoved int
	// CountRemaining is the number of memories that passed the firewall.
	CountRemaining int
}

FilterResult holds the outcome of a PostFilter call.

type PreQueryDenial

type PreQueryDenial struct {
	Code   string
	Reason string
}

PreQueryDenial is returned by PreQuery when the query itself is forbidden before any data is fetched. The caller should return HTTP 403.

func (*PreQueryDenial) Error

func (d *PreQueryDenial) Error() string

Error implements the error interface.

type RetrievalFirewall

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

RetrievalFirewall enforces sensitivity label, classification tier, and namespace isolation policies on retrieval results. All state is held in struct fields — no package-level variables.

INVARIANT: blocked_labels are ABSOLUTE. No admin bypass. No override. Reference: Tech Spec Addendum Section A3.5.

func New

func New(cfg config.DaemonRetrievalFirewallConfig, logger *slog.Logger) *RetrievalFirewall

New creates a RetrievalFirewall from the daemon-level configuration. When cfg.Enabled is false, PreQuery and PostFilter are no-ops with zero overhead.

func (*RetrievalFirewall) Enabled

func (fw *RetrievalFirewall) Enabled() bool

Enabled returns whether the retrieval firewall is active.

func (*RetrievalFirewall) PostFilter

func (fw *RetrievalFirewall) PostFilter(
	src *config.Source,
	records []destination.TranslatedPayload,
) FilterResult

PostFilter removes memories that the source is not permitted to see based on blocked_labels, max_classification_tier, required_labels, and namespace isolation rules. It returns a FilterResult describing what was removed.

INVARIANT: blocked_labels are ABSOLUTE. No admin bypass. No debug bypass. INVARIANT: At most 0.1ms per result — metadata only, no content inspection.

Reference: Tech Spec Addendum Section A3.5 — Post-retrieval.

func (*RetrievalFirewall) PreQuery

func (fw *RetrievalFirewall) PreQuery(src *config.Source, namespace string) *PreQueryDenial

PreQuery performs Stage 0 access-level checks before any data is fetched. Returns nil when the query is allowed, or a *PreQueryDenial when blocked.

Checks:

• If the source has a max_classification_tier that is not recognized in tier_order, the query is denied (unknown tiers = maximally restricted).

Reference: Tech Spec Addendum Section A3.5 — Pre-query.

func (*RetrievalFirewall) TierIndex

func (fw *RetrievalFirewall) TierIndex(tier string) int

TierIndex returns the ordinal index for a tier name, or -1 if unknown. Exported for testing.

func (*RetrievalFirewall) WithMetrics

func (fw *RetrievalFirewall) WithMetrics(
	filteredTotal *prometheus.CounterVec,
	deniedTotal *prometheus.CounterVec,
	latency *prometheus.HistogramVec,
) *RetrievalFirewall

WithMetrics attaches Prometheus metrics to the firewall.