pluginsdk

type BuildRequest struct {
	// Kind is "credential", "tunnel", or "endpoint".
	Kind         string
	TypeName     string
	InstanceName string
	// ConfigJSON is the HCL block body decoded against the declared
	// Schema and marshaled as a JSON object. Decode it into your
	// plugin-native struct via Decode.
	ConfigJSON []byte
}

type Capabilities struct {
	// Network is the plugin's network requirement. Defaults to
	// NetworkNone (the plugin only talks to the gateway over its
	// socket).
	Network NetworkAccess

	// Egress is the set of upstream targets this plugin needs to reach
	// through the gateway's brokered dial (conn.DialUpstream), each
	// "host:port" or "*.suffix.tld:port" (port required). Declaring it
	// lets a plugin run with Network = NetworkNone — no raw sockets,
	// every connection gateway-validated and audited — instead of the
	// coarse NetworkOutbound. The gateway records the approved set in its
	// lockfile (trust-on-first-use) and blocks an upgrade that broadens
	// it, the same model as Network; the operator never hand-writes it.
	Egress []string

	// Privileged declares that this plugin cannot run sandboxed and needs
	// full host access — to exec arbitrary helper tools (ssh, kubectl,
	// aws, ...), read the user's tool configs (~/.ssh, ~/.aws, ~/.kube),
	// and so on. It is the same grant as the operator-written
	// `sandbox = "off"` HCL attribute, just plugin-declared. Unlike
	// Network and Egress it is NOT trust-on-first-use: handing a plugin
	// full host access is too dangerous to grant silently, so the gateway
	// holds the plugin closed until the operator explicitly approves it
	// (clawpatrol plugins approve, or the dashboard). An upgrade re-pends
	// approval. Prefer a narrower capability (Egress, a built-in tunnel)
	// whenever one fits; reach for this only when the plugin genuinely
	// must shell out.
	Privileged bool
}

type Conn struct {
	net.Conn

	EndpointTypeName        string
	EndpointInstance        string
	EndpointCanonicalConfig []byte // canonical JSON the endpoint Build returned

	Profile      string
	PeerIP       string
	UpstreamHost string
	DstPort      uint16

	CredentialTypeName        string
	CredentialInstance        string
	CredentialSecret          []byte
	CredentialExtras          map[string]string
	CredentialCanonicalConfig []byte

	// Credentials is every credential bound to this endpoint, in
	// declaration order, for plugins that support multi-credential
	// endpoints (e.g. a base key per account). The singular Credential*
	// fields above mirror Credentials[0]. On single-credential endpoints
	// it holds that one credential; on older gateways that don't send the
	// set it is nil (read the singular fields instead).
	Credentials []ConnCredential

	// SessionToken scopes this connection's calls to the gateway's
	// host-served HostControl service. The SDK threads it into
	// Conn.Evaluate automatically (as request metadata); plugin authors
	// don't use it directly.
	SessionToken string

	TunnelTypeName string
	TunnelInstance string
	// contains filtered or unexported fields
}

type ConnCredential struct {
	TypeName        string
	Instance        string
	Secret          []byte
	Extras          map[string]string
	CanonicalConfig []byte
}

type ConnEvent struct {
	Action  string // "allow" | "deny" | "hitl_allow" | "hitl_deny" | "error"
	Reason  string
	Verb    string
	Summary string
	Bytes   int64
	Facets  map[string]any
	Rule    string
}

type CredentialBuildResult struct {
	Canonical any
	Metadata  CredentialMetadata
}

type CredentialDef struct {
	TypeName string
	Schema   Schema

	// Disambiguators names registration-time supported dispatch
	// discriminator fields, e.g. "placeholder" for HTTP bearer-style
	// credentials. The gateway validates credential/profile HCL against
	// this list.
	Disambiguators []string

	// HTTPInject declares that this credential can inject into the
	// built-in HTTPS endpoint via InjectHTTP.
	HTTPInject bool

	// Build is optional. When set, the gateway invokes it once per
	// HCL block at config-load time. The plugin can validate the
	// decoded body, fill defaults, and return either a canonical form
	// or CredentialBuildResult. When nil, the SDK echoes the request
	// body unchanged.
	Build func(req BuildRequest) (any, error)

	// InjectHTTP is called for credentials bound to a built-in HTTPS
	// endpoint when HTTPInject is true. Header-only: the request body does
	// not flow through the plugin.
	InjectHTTP func(ctx context.Context, req HTTPInjectRequest) (*HTTPInjectResponse, error)

	// HTTPTransform declares that this credential rewrites more than
	// headers — the request method / URL / body — via TransformHTTP.
	// Implies HTTPInject. Use for credentials that sign over the body (AWS
	// SigV4) or carry the secret in the URL/body (telegram, discord).
	HTTPTransform bool

	// TransformHTTP is called for HTTPTransform credentials. It receives
	// the request body as a stream (req.Body) and returns the mutations
	// plus the transformed body. Buffering is the plugin's choice: read
	// only what you need and stream the rest, or read it all to sign. See
	// HTTPTransformRequest / HTTPTransformResponse.
	TransformHTTP func(ctx context.Context, req HTTPTransformRequest) (*HTTPTransformResponse, error)
}

type CredentialMetadata struct {
	Disambiguators []string
	SecretSlots    []SecretSlot
	EnvVars        []EnvVar
	OAuth          *OAuthIntegration
	HTTPInject     bool
	// HTTPTransform mirrors CredentialDef.HTTPTransform (the credential
	// rewrites method/URL/body via TransformHTTP). Registration-time only.
	HTTPTransform bool
}

type DialUpstreamFunc func(ctx context.Context, network, addr string) (net.Conn, error)

type DialUpstreamOptions struct {
	// TLS asks the gateway to terminate upstream TLS: the gateway
	// performs real certificate verification (system roots plus the
	// endpoint's TLS configuration and any mTLS credential) and the
	// plugin exchanges plaintext over the brokered pipe. Preferred
	// over running tls.Client inside the plugin — sandboxed plugins
	// may not even have a CA bundle mounted.
	TLS bool
	// TLSServerName overrides the SNI / verification name. Defaults
	// to the host part of addr.
	TLSServerName string
}

type EndpointDef struct {
	TypeName string
	// Family is forwarded to *config.Plugin.Family. Use "stream" so
	// CEL rules can't accidentally try to match http.* / sql.*
	// against this endpoint.
	Family      string
	TLSMode     TLSMode
	RequiresVIP bool
	Schema      Schema
	Build       func(req BuildRequest) (any, error)
	// HandleConn owns the agent connection. The SDK has already (a)
	// terminated TLS for TLSMode=TLSTerminate and (b) populated
	// conn.* with the per-conn context. Return nil for a clean close,
	// or any error to log + close.
	HandleConn func(ctx context.Context, conn *Conn) error
}

type EnvVar struct {
	Name        string
	Value       string
	Description string
}

type FacetDef struct {
	Name   string
	Fields []FacetField
	// ResultFields is the after-the-fact schema a plugin reports via
	// Conn.SetResult once an action's response is known. It mirrors Fields
	// (same FacetField type, so Description/Title/DetailOnly and the
	// FacetStream kind apply): the field marked Title becomes the action's
	// status, a FacetStream field is a response body the gateway caps.
	// Empty for facets that report nothing after the response.
	ResultFields []FacetField
}

type FacetField struct {
	Name     string
	Kind     FacetKind
	Label    string
	Optional bool
	// Description is a human explanation of the field, shown in the
	// dashboard's per-action facet table (e.g. "API action (CloudTrail)").
	// Falls back to Label when empty.
	Description string
	// Title marks this as the action's primary identifier — shown as the
	// activity log's "verb" instead of the HTTP method. At most one field
	// per facet should set it (e.g. an AWS plugin marks iam_action).
	Title bool
	// DetailOnly keeps the field out of the compact activity-log row (it
	// still appears in the per-action detail). Use for fields the Title
	// makes redundant (e.g. AWS action/service once iam_action is Title).
	DetailOnly bool
}

type FacetKind int

type HTTPInjectRequest struct {
	CredentialTypeName        string
	CredentialInstance        string
	CredentialCanonicalConfig []byte
	CredentialSecret          []byte
	CredentialExtras          map[string]string

	Method  string
	URL     string
	Host    string
	Headers http.Header

	BodyPrefix    []byte
	BodyTruncated bool
}

type HTTPInjectResponse struct {
	Headers []HeaderMutation
	// Redactions lists exact derived secret strings the gateway should mask from
	// audit samples. Include any exchanged JWTs, HMAC signatures, or other values
	// derived from CredentialSecret that are injected into non-sensitive headers.
	Redactions []string
}

type HTTPTransformRequest struct {
	CredentialTypeName        string
	CredentialInstance        string
	CredentialCanonicalConfig []byte
	CredentialSecret          []byte
	CredentialExtras          map[string]string

	Method  string
	URL     string
	Host    string
	Headers http.Header

	// Body is the request body, streamed from the gateway. Read as much
	// as you need — the plugin controls buffering. Reading to EOF is fine
	// (the gateway streams the whole body); reading a prefix and returning
	// a Body that copies the rest through is also fine.
	Body io.Reader
}

type HTTPTransformResponse struct {
	// Headers / Method / URL rewrite the request line and headers; applied
	// by the gateway before the request is forwarded. A credential that
	// signs over the body sets the signature header here (and a
	// Content-Length header if it changed the body length).
	Headers []HeaderMutation
	Method  string
	URL     string
	// Redactions are exact derived secret strings to mask from audit
	// samples (a computed signature, an exchanged token).
	Redactions []string

	// Body is the outgoing request body the gateway forwards upstream. To
	// pass the input through unchanged, set Body = req.Body. To replace it,
	// return any io.Reader (e.g. bytes.NewReader). nil sends an empty body.
	//
	// HTTP trailers that follow the request body (e.g. gRPC's) are
	// preserved by the gateway across the transform; the plugin does not
	// handle them.
	Body io.Reader
}

type HeaderMutation struct {
	Op     HeaderMutationOp
	Name   string
	Values []string
}

type HeaderMutationOp string

type NetworkAccess int

type OAuthConfig struct {
	ClientID     string
	ClientSecret string
	AuthURL      string
	TokenURL     string
	DeviceURL    string
	RegisterURL  string
	RedirectURI  string
	Scopes       []string
	RefreshToken string
}

type OAuthIntegration struct {
	Type           string
	Header         string
	Prefix         string
	Flow           string
	OAuth          OAuthConfig
	OptionalScopes []OptionalScopeGroup
}

type OptionalScope struct {
	ID    string
	Label string
}

type OptionalScopeGroup struct {
	Title  string
	Scopes []OptionalScope
}

type Plugin struct {
	Name        string
	Version     string
	Credentials []CredentialDef
	Tunnels     []TunnelDef
	Endpoints   []EndpointDef

	// Capabilities declares the low-risk permissions this plugin
	// needs. The gateway records the approved set in its lockfile on
	// first load (the operator no longer hand-writes them) and fails
	// closed with a loud warning if a later version of the plugin
	// asks for more. Today the only capability is Network: set it to
	// NetworkOutbound if the plugin dials out itself (a tunnel
	// transport, or a credential plugin doing its own token
	// exchange). High-risk grants — host filesystem access,
	// sandbox = "off" — are operator-only and are NOT declarable
	// here.
	Capabilities Capabilities
	// Facets is the per-plugin schema list for protocol families the
	// plugin's endpoints emit actions against. The gateway registers
	// one facet.Runtime per FacetDef so the dashboard's /api/facets
	// surfaces the schema and rules can compile CEL conditions
	// against it (e.g. `smtp.verb == "MAIL"`). Names are auto-
	// namespaced to "<plugin>.<facet>".
	Facets []FacetDef
}

type Schema struct {
	Fields []SchemaField
}

type SchemaField struct {
	Name       string
	TypeString string
	Required   bool
}

type SecretSlot struct {
	Name        string
	Label       string
	Multiline   bool
	Description string
}

type StateStore struct{}

type StreamValue struct {
	R io.Reader
}

type TLSMode int

type TunnelDef struct {
	TypeName string
	Schema   Schema
	Build    func(req BuildRequest) (any, error)
	// Open is invoked on the first Acquire of a tunnel instance. It
	// returns the handle the SDK passes back to Dial / Close. Open is
	// optional for stateless tunnels; the SDK supplies a no-op default
	// returning the instance name as the handle.
	Open func(ctx context.Context, req TunnelOpenRequest) (any, error)
	// Dial opens one upstream connection through the tunnel handle.
	// The SDK exposes a duplex net.Conn-like upstream object the
	// plugin reads from / writes to as if it were the upstream socket.
	Dial func(ctx context.Context, req TunnelDialRequest, upstream net.Conn) error
	// Close tears down the handle. May be nil for stateless tunnels.
	Close func(ctx context.Context, handle any) error
}

type TunnelDialRequest struct {
	Handle  any
	Network string
	Addr    string
	// DialUpstream opens an upstream transport connection for this tunnel,
	// gateway-routed (direct or via the parent) — the same primitive as on
	// TunnelOpenRequest, for tunnels that establish their transport
	// per-Dial (e.g. a SOCKS tunnel dialing the proxy on each Dial).
	DialUpstream DialUpstreamFunc
}

type TunnelOpenRequest struct {
	TunnelTypeName   string
	TunnelInstance   string
	CanonicalConfig  []byte
	CredentialSecret []byte
	CredentialExtras map[string]string
	// DialUpstream opens this tunnel's own transport connection — the
	// socket the tunnel rides on to reach its endpoint (a "udp" conn to a
	// WireGuard endpoint, a "tcp" conn to an SSH bastion). The gateway
	// dials on the plugin's behalf and routes it directly, or through the
	// parent tunnel when this tunnel is chained (`via = <tunnel>`). Use it
	// instead of opening a raw socket, so the tunnel plugin can run with no
	// network capability of its own and the gateway owns the composition.
	// nil only against an old gateway with no HostTunnel support.
	DialUpstream DialUpstreamFunc
}

type Verdict struct {
	// Action is "allow" | "deny" | "hitl_allow" | "hitl_deny" |
	// "error". The plugin maps this onto whatever protocol-level
	// response code makes sense (250/535 for SMTP, etc.).
	Action string
	Reason string
	// Rule is the matched CompiledRule.Name, or "" when no rule
	// matched (the gateway's default-deny took effect).
	Rule string
}