piguard

type Action string

type Aggregate struct {
	Result
	// Degraded is true when fewer than MinOK detectors returned StatusOK. The caller
	// must map a degraded aggregate to review — NOT allow, NOT block.
	Degraded bool
	// MinAction is a deterministic force-override floor: when a high-confidence
	// deterministic marker is present (e.g. Unicode Tags-block smuggling, or
	// truncated/unscannable content), the applied action is at least this severe
	// regardless of score. ActionAllow when no override fires.
	MinAction Action
	// Truncated is true when DecodedSignals.Truncated (the content exceeded the
	// extraction-level scan cap) OR any StatusOK detector reported its own
	// Result.Truncated (e.g. Gemini's provider-side content-length cap cut off part
	// of the message before it was even sent) — either way, only partially
	// inspected. Folded into MinAction (→ review) but exposed for audit/metrics.
	Truncated bool
	// PerDetector retains every detector's raw Result (including timeouts/errors)
	// for audit and for writing protection_events rows.
	PerDetector []Result
}

type Category struct {
	Name       string  `json:"name"`
	NativeCode string  `json:"native_code,omitempty"`
	Score      float64 `json:"score,omitempty"`
}

type DecodedSignals struct {
	// UnicodeTags reports U+E0000–U+E007F "ASCII smuggling" characters: ASCII
	// mirrored into an invisible Unicode block that LLM tokenizers still read.
	UnicodeTags bool
	// ZeroWidth reports zero-width/invisible separators (U+200B–U+200D, U+2060,
	// U+FEFF) used to hide or fragment instructions.
	ZeroWidth bool
	// HiddenCSSText reports text hidden from humans via CSS (display:none,
	// font-size:0, white-on-white, visibility:hidden, mso-hide:all, off-screen).
	HiddenCSSText bool
	// HomoglyphRatio is the fraction of letters that are non-ASCII confusables
	// (Cyrillic/Greek lookalikes) — a spoofing/obfuscation signal. 0..1.
	HomoglyphRatio float64
	// Unscannable reports a part whose bytes could not be scanned (a genuinely
	// binary attachment, no OCR in v1). Routed to review — no finding != benign.
	Unscannable bool
	// FragmentedURL reports reassembly-style obfuscation ("join 'h','ttp',…").
	FragmentedURL bool
	// PlainHTMLDiverge reports that the text/plain and visible text/html parts carry
	// materially different content (the human reads one, the agent may read the
	// other).
	PlainHTMLDiverge bool
	// Truncated reports that extraction stopped at the scan size cap — content beyond
	// the cap was not inspected, so "no finding" is not a safety guarantee.
	Truncated bool
}

type Detector interface {
	// Inspect screens req and returns a normalized verdict. A returned error and a
	// non-OK Result.Status both signal "no usable verdict"; the Engine treats them
	// identically (excluded from the aggregate).
	//
	// Implementations MUST return promptly when ctx is cancelled or times out. The
	// Engine bounds each call with a timeout, but Go cannot force-cancel a goroutine:
	// a detector that ignores ctx and blocks leaks one goroutine per call. Network
	// backends must pass ctx into their request.
	Inspect(ctx context.Context, req Request) (*Result, error)
	// Name is the stable adapter id, e.g. "heuristics", "lakera".
	Name() string
}

type Direction int

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

type EngineConfig struct {
	// Weights is the per-detector weight in the aggregate (by Detector.Name).
	// Missing → 1.0.
	Weights map[string]float64
	// Timeout bounds each detector's Inspect. A detector that exceeds it is recorded
	// as StatusTimeout and EXCLUDED from the aggregate (never counted as benign).
	Timeout time.Duration
	// MinOK is the minimum number of detectors that must return StatusOK for the
	// aggregate to be trusted. Below it, the Engine reports Degraded → the caller
	// maps to review (fail-to-review). Default 1.
	MinOK int
}

type GeminiConfig struct {
	// Model is the Gemini model name. When empty, NewGeminiDetector falls back to
	// the GEMINI_EVAL_MODEL environment variable, then to geminiDefaultModel.
	Model string
	// APIKey is the Google AI Studio key. When empty, NewGeminiDetector falls back
	// to the GEMINI_API_KEY and GOOGLE_API_KEY environment variables. Never log or
	// include this value in error messages.
	APIKey string
	// MaxRetries is the number of retries on transient API errors (429, 5xx).
	// Default geminiDefaultMaxRetries.
	MaxRetries int
	// HTTPClient allows injecting a custom *http.Client (e.g. for tests). When nil
	// a default client with a 30 s timeout is used.
	HTTPClient *http.Client
}

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

type HeuristicsDetector struct{}

type ProviderMeta struct {
	Name          string         `json:"name"`
	ModelVersion  string         `json:"model_version,omitempty"`
	NativeVerdict string         `json:"native_verdict,omitempty"`
	NativeScore   string         `json:"native_score,omitempty"`
	LatencyMS     int            `json:"latency_ms,omitempty"`
	Raw           map[string]any `json:"raw,omitempty"`
}

type Request struct {
	Direction Direction
	Segments  []Segment
	Signals   DecodedSignals
	// Sender is the claimed RFC 5322 From (inbound) or the agent identity
	// (outbound). Consult Auth.DMARC before treating the inbound domain as verified.
	Sender string
	// Auth is the parsed inbound auth verdict; nil on outbound.
	Auth *emailauth.Authentication
	// SizeBytes is the total extracted text size (post-cap).
	SizeBytes int
}

type Result struct {
	Flagged    bool         `json:"flagged"`
	Score      float64      `json:"score"`
	Categories []Category   `json:"categories,omitempty"`
	Spans      []Span       `json:"spans,omitempty"`
	Status     Status       `json:"status"`
	Provider   ProviderMeta `json:"provider"`
	// Truncated reports that this detector only inspected a prefix of the content
	// (e.g. a provider-side context-window cap) — a "no finding" from THIS detector
	// is not a safety guarantee. Distinct from DecodedSignals.Truncated, which
	// reports extraction-level truncation (the 1 MiB scan cap) shared by all
	// detectors; this field is per-detector and additive to the Engine's
	// force-override floor (see Engine.forceFloor).
	Truncated bool `json:"truncated,omitempty"`
}

type Segment struct {
	Type    SegmentType
	Content string
	Ref     string
}

type SegmentType string

type Span struct {
	Start int    `json:"start"`
	End   int    `json:"end"`
	Text  string `json:"text,omitempty"`
	Label string `json:"label,omitempty"`
	Ref   string `json:"ref,omitempty"`
}

type Status int