registry

type FieldSpec struct {
	Type      string   `yaml:"type"` // "string" | "number" | "bool"
	Required  bool     `yaml:"required"`
	Enum      []string `yaml:"enum,omitempty"`
	Pattern   string   `yaml:"pattern,omitempty"`
	MaxLength int      `yaml:"max_length,omitempty"`
	MaxValue  *float64 `yaml:"max_value,omitempty"` // numeric ceiling, e.g. caps a result-count/limit argument directly in the schema
}

type PreImage struct {
	Method  string `yaml:"method,omitempty"`
	Path    string `yaml:"path,omitempty"`
	MCPTool string `yaml:"mcp_tool,omitempty"`
}

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

type ReversibilityClass string

type Tool struct {
	Name string `yaml:"name"`
	// Description is what an agent sees in tools/list when this proxy
	// fronts an MCP server - carried through from the upstream's own
	// description. Without it an agent behind the proxy can't choose tools.
	Description        string               `yaml:"description,omitempty"`
	ReversibilityClass ReversibilityClass   `yaml:"reversibility_class"`
	Method             string               `yaml:"method"`
	Path               string               `yaml:"path"`
	ResourceArg        string               `yaml:"resource_arg"`
	ArgsSchema         map[string]FieldSpec `yaml:"args_schema"`
	SanitizeFields     []string             `yaml:"sanitize_fields,omitempty"`   // dot-paths stripped from the upstream response
	CompensateWith     string               `yaml:"compensate_with,omitempty"`   // Class A - empty means the tool re-issues itself
	CompensateFields   []string             `yaml:"compensate_fields,omitempty"` // Class A - arg names restored from the pre-image on compensation
	PreImage           *PreImage            `yaml:"pre_image,omitempty"`         // Class A
	Deferrable         bool                 `yaml:"deferrable,omitempty"`        // Class C tier 2
	HoldSeconds        int                  `yaml:"hold_seconds,omitempty"`      // Class C tier 2
	ReviewerRole       string               `yaml:"reviewer_role,omitempty"`     // Class C tier 3

	// ReviewedBy/ReviewedAt are purely informational in normal operation -
	// nothing in validateToolDefinition checks them, and a catalog missing
	// both loads exactly as it always has. They only become load-bearing
	// when a deployment opts into require_reviewed_tools (cmd/rinwall's
	// Config, checked via RequireReviewed below): the structural gate
	// against the one realistic way to end up running an unreviewed
	// catalog in production - piping `blastradius --emit-registry`
	// straight into service without a human ever looking at it. See
	// RequireReviewed's own doc comment for the full reasoning.
	ReviewedBy string `yaml:"reviewed_by,omitempty"`
	ReviewedAt string `yaml:"reviewed_at,omitempty"` // RFC3339 or YYYY-MM-DD

	// ProvenanceJudge opts this specific tool into the model-based
	// provenance add-on (internal/provenance) - off by default. An org
	// enables it per sensitive tool (close_account) while leaving
	// low-stakes ones on the cheaper self-reported/no-taint path. Only
	// takes effect when the caller also supplies a context window with
	// the call; the tool setting alone does nothing without that.
	ProvenanceJudge bool `yaml:"provenance_judge,omitempty"`

	// VisualProvenanceJudge opts this tool into the screenshot-reasoning
	// analog of ProvenanceJudge (internal/visualprovenance) - for the
	// "computer use" tool shape (one generic tool, an action
	// discriminator, no semantic tool name to classify) rather than the
	// text judge's confused-deputy check. Deliberately triggered
	// INDEPENDENT of ReversibilityClass in internal/handler, not folded
	// into the existing A/C-only taint gate - that gate would silently
	// never reach a Class-B-registered "computer" tool, which is the
	// realistic outcome for a tool whose danger varies per call rather
	// than by name. Requires the caller to supply a screenshot AND their
	// own stated reasoning for the action alongside the call; absent
	// either, this setting does nothing, same as ProvenanceJudge without
	// a context window.
	VisualProvenanceJudge bool `yaml:"visual_provenance_judge,omitempty"`

	// VisualJudgeActionArg/VisualJudgeTriggerValues are the cost filter: a
	// real multimodal model call on every scroll and screenshot is a cost
	// nobody wants, and most of a computer-use tool's calls are exactly
	// that - inert. VisualJudgeActionArg names which argument holds an
	// action-type discriminator (e.g. "action" on Anthropic's own
	// computer-use tool shape); the visual judge only runs when that
	// argument's value is one of VisualJudgeTriggerValues (e.g.
	// left_click, type) - not on screenshot/scroll/arrow-key calls, which
	// can't meaningfully be "manufactured by deceptive content" the way a
	// click or a typed value can. Leaving VisualJudgeActionArg empty means
	// no filter - every call to a VisualProvenanceJudge tool triggers the
	// check, the honest (costlier) default for a tool with no action-type
	// convention to filter on at all.
	VisualJudgeActionArg     string   `yaml:"visual_judge_action_arg,omitempty"`
	VisualJudgeTriggerValues []string `yaml:"visual_judge_trigger_values,omitempty"`

	// DBRole/Query/QueryArgs make this tool database-backed instead of
	// HTTP-backed - the real Vault dynamic-secrets path (a genuine
	// database/creds/<DBRole> mint, executing a real CREATE ROLE against
	// the actual database) rather than a biscuit token verified by an
	// HTTP upstream. DBRole names a Vault database secrets engine role;
	// Query is a parameterized SQL statement ($1, $2, ...); QueryArgs
	// names which validated args_schema fields fill those placeholders,
	// in order. Mutually exclusive with Method/Path - see
	// validateToolDefinition. Restricted to Class B for now: a raw SQL
	// mutation's compensation semantics (what's the "pre-image" of an
	// UPDATE with an arbitrary WHERE clause?) aren't designed yet.
	DBRole    string   `yaml:"db_role,omitempty"`
	Query     string   `yaml:"query,omitempty"`
	QueryArgs []string `yaml:"query_args,omitempty"`

	// AWSRole/S3Bucket/S3KeyArg make this tool AWS-backed instead of
	// HTTP- or DB-backed - the real Vault AWS dynamic-secrets path (a
	// genuine sts:AssumeRole against the actual AWS account). Unlike
	// DBRole, a fresh credential is minted on EVERY call, not cached per
	// session - a real AssumeRole is cheap and AWS-TTL-enforced, unlike a
	// database CREATE ROLE, so there's no cost reason to reuse one across
	// calls, and every reason not to (shorter-lived exposure per call).
	// AWSRole names a Vault AWS secrets engine role; S3Bucket is the
	// bucket to read from; S3KeyArg names which validated args_schema
	// field supplies the object key. Scoped to a single S3 GetObject for
	// now, matching DBRole's own scope discipline (Class B, read-only).
	AWSRole  string `yaml:"aws_role,omitempty"`
	S3Bucket string `yaml:"aws_s3_bucket,omitempty"`
	S3KeyArg string `yaml:"aws_s3_key_arg,omitempty"`

	// MCPTool makes this tool MCP-backed: the proxy forwards the call
	// onward to an upstream MCP server (internal/mcpclient) as a real
	// tools/call, instead of an HTTP route, a SQL query, or an S3 read.
	// This is the shape that lets the firewall sit in front of an MCP
	// server someone already runs, which is the whole adoption story - an
	// MCP tool advertises no upstream HTTP route, so before this existed a
	// scanned catalog could not be loaded without a human hand-writing
	// method/path for every entry.
	//
	// Unlike DBRole and AWSRole, this is NOT restricted to Class B. Those
	// two are read-only scopes this build deliberately hasn't extended to
	// mutations yet; an upstream MCP server's catalog is the general case
	// and routinely contains genuinely irreversible tools - refusing to
	// load them would just push exactly the calls that most need gating
	// back outside the firewall. Class A works too, via PreImage.MCPTool.
	//
	// The name may differ from Tool.Name: the agent-facing name is
	// whatever this catalog calls it, MCPTool is what the upstream server
	// calls it. Empty means "same as Name," which is the normal case for
	// a catalog produced by scanning that server.
	MCPTool string `yaml:"mcp_tool,omitempty"`
}