recipe

type AuthKind int

type AuthSpec struct {
	Kind        AuthKind
	HeaderName  string // for Header
	ValuePrefix string // for Header (e.g. "token ", "SSWS ")
	UserField   string // for Basic
	PassField   string // for Basic
	TokenField  string // Fields key holding the secret; defaults to "token"
	// RawAuth, with PreAuthed, sets Authorization to ValuePrefix+token instead of
	// the default "Bearer " scheme (e.g. CyberArk PVWA's raw session token).
	RawAuth bool
}

type Call struct {
	Method       string // default GET
	Path         string // appended to Base; may template {field}
	Accept       string
	ReadOnlyPOST bool
	Body         string
	Fields       []Extract
	Count        *CountSpec
	Signals      []Signal
	Optional     bool // a failure here doesn't abort the whole recon
}

type CountSpec struct {
	Key          string
	Path         string // count = numeric value at path, or array length at path
	ArrayLen     bool   // treat Path as an array and use its length
	FromLinkLast bool   // parse Link rel="last" page number from the response
	Flag         module.FlagLevel
}

type Extract struct {
	Key  string
	Path string // dotted JSON path
	Flag module.FlagLevel
}

type HTTP struct {
	Rule       string            // gitleaks rule id (routing); may be empty for custom-recognized
	ModuleName string            // overrides the module name (defaults to Rule)
	Base       string            // base URL, may template {field}
	Accept     string            // default Accept header for all calls
	Headers    map[string]string // static extra headers on every request
	Auth       AuthSpec
	Whoami     Call
	Calls      []Call // additional inventory/count calls
	// Endpoint declares where this module's credential may legitimately be sent.
	// Required for any spec whose Base is templated on a URL-valued field; the
	// catalog guard test fails without it. See module.EndpointPolicy.
	Endpoint module.EndpointPolicy
	// MultiScope marks an API where the whoami can 401 for a token that is still
	// live against a different scope (e.g. Cloudflare's user-scoped
	// /user/tokens/verify rejects an account/zone-scoped token). For these we keep
	// probing the other calls after a whoami 401 instead of stopping early, so a
	// scoped-but-live key isn't falsely declared DEAD. Default off preserves the
	// OPSEC early-stop for single-scope APIs.
	MultiScope bool
	// TitlePrefix is shown before the redacted key in the note title.
	TitlePrefix string
	// Summarize, if set, produces the one-line takeaway from findings.
	Summarize func([]module.Finding) string
	// Authenticate, if set, runs the optional headless token exchange before
	// recon; its Token is attached when Auth.Kind == PreAuthed.
	Authenticate func(ctx context.Context, c *recon.Client, f module.Fields) (module.Token, error)
	// Static findings are appended unconditionally (e.g. "scopes not
	// introspectable read-only" for restricted keys).
	Static []module.Finding
	// Harvest, if set, extracts downstream secret values for recursive triage.
	// The pipeline only invokes it under --live --intrusive within the bounded
	// recursion budget; implementations must self-gate on c.Live()/c.Intrusive().
	Harvest func(ctx context.Context, c *recon.Client, t module.Token, f module.Fields) ([]module.Harvested, error)
}

type Signal struct {
	Path     string // JSON path to inspect (string or joined array)
	Contains string // substring trigger
	Regex    string // regex trigger (alternative to Contains)
	Key      string // finding key to emit
	Value    string // finding value (defaults to the matched field value)
	Flag     module.FlagLevel
}