localcontrol

type Config struct {
	// Version is the platform's revision of this document. It is echoed in reports so an operator
	// can tell which endpoints have converged.
	Version int `json:"version"`
	// Mode is the local posture. Empty → warn.
	Mode Mode `json:"mode"`

	// Detectors toggles and tunes each built-in detector. A detector absent from the payload keeps
	// its default (enabled), because a truncated or partially-written config must fail toward
	// protection rather than away from it.
	DatabaseSafety  *DatabaseSafetyConfig  `json:"databaseSafety,omitempty"`
	SecretScan      *SecretScanConfig      `json:"secretScan,omitempty"`
	PromptInjection *PromptInjectionConfig `json:"promptInjection,omitempty"`
	TokenBudget     *TokenBudgetConfig     `json:"tokenBudget,omitempty"`

	// Scope narrows which components the local layer inspects at all. Exclusions win over
	// inclusions. Empty include lists mean "everything not excluded".
	IncludeComponents []string `json:"includeComponents,omitempty"`
	IncludePatterns   []string `json:"includePatterns,omitempty"`
	IncludeTypes      []string `json:"includeTypes,omitempty"`
	ExcludeComponents []string `json:"excludeComponents,omitempty"`
	ExcludePatterns   []string `json:"excludePatterns,omitempty"`
	ExcludeTypes      []string `json:"excludeTypes,omitempty"`
}

type DatabaseSafetyConfig struct {
	// Disabled turns the detector off. Expressed as an opt-OUT so that the zero value of an
	// omitted config block is "enabled", matching Config's fail-toward-protection rule.
	Disabled bool `json:"disabled,omitempty"`
	// AllowedPatterns are escape hatches: a query matching one is exempt even if it also matches a
	// danger pattern. This is how a known-safe `DELETE FROM session_cache WHERE ...` gets through.
	AllowedPatterns []string `json:"allowedPatterns,omitempty"`
	// BlockedPatterns extend the built-in danger set with org-specific rules.
	BlockedPatterns []string `json:"blockedPatterns,omitempty"`
	// ToolPatterns overrides which component names are treated as database tools. Empty keeps the
	// built-in list.
	ToolPatterns []string `json:"toolPatterns,omitempty"`
}

type Detector interface {
	// Name is the stable identifier used in verdicts and config.
	Name() string
	// Stages the detector runs at. A detector is never consulted at other stages.
	Stages() []enforce.Stage
	// Priority orders execution, higher first. It matters because the engine stops at the first
	// blocking verdict, so the cheapest and most certain rules should run before the fuzzier ones.
	Priority() int
	// Inspect returns a finding, or nil when there is nothing to report.
	Inspect(req *Request) *Verdict
}

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

type Mode string

type PromptInjectionConfig struct {
	Disabled bool `json:"disabled,omitempty"`
	// BlockThreshold is the minimum severity that blocks in enforce mode. Empty → high, matching
	// the Python SDK's block_threshold=ThreatLevel.HIGH.
	BlockThreshold Severity `json:"blockThreshold,omitempty"`
	// ExtraPatterns add org-specific injection phrasings.
	ExtraPatterns []string `json:"extraPatterns,omitempty"`
}

type Request struct {
	Stage enforce.Stage
	// ComponentType is "TOOL" or "LLM", matching the wire vocabulary.
	ComponentType string
	// ComponentName is the tool or model name, used for scoping and for the audit message.
	ComponentName string
	// Content is the text to inspect: tool arguments at tool_call, model output at post_llm.
	Content string
	// SessionID scopes stateful detectors (the token budget). Empty means unscoped, which the
	// budget detector treats as a single shared bucket rather than as "no budget".
	SessionID string
	// Tokens is this call's token count, when the caller knows it. Zero means unknown, not free.
	Tokens int
}

type SecretScanConfig struct {
	Disabled bool `json:"disabled,omitempty"`
	// ExtraPatterns add org-specific credential shapes (an internal token prefix, say).
	ExtraPatterns []string `json:"extraPatterns,omitempty"`
}

type Severity string

type TokenBudgetConfig struct {
	Disabled bool `json:"disabled,omitempty"`
	// MaxTokens is the per-session ceiling. Zero means no ceiling — the budget detector is inert
	// rather than blocking everything, which is what an unset limit has to mean.
	MaxTokens int `json:"maxTokens,omitempty"`
}

type Verdict struct {
	// Action is what the posture says to do about this finding.
	Action enforce.Action
	// Detector names the rule that fired, so an operator can find and tune it.
	Detector string
	// Reason is a stable machine-readable code ("destructive_query", "prompt_injection"). It is
	// part of the contract with the audit trail — rename it and dashboards break.
	Reason string
	// Message is the human sentence shown to whoever is blocked.
	Message string
	// Severity of the finding itself, independent of Action.
	Severity Severity
	// Matched is the excerpt that triggered the rule, bounded by clipMatch. Included because a
	// block with no evidence is unactionable, truncated because the content can be a whole prompt
	// and this ends up in logs.
	Matched string
}