module

type Base struct{}

type Candidate struct {
	Value  string            // the raw credential string (a token, key, JSON, etc.)
	Source SourceKind        // how it was parsed
	File   string            // origin filename/label, if any
	Vars   map[string]string // co-located key/value pairs (env, dotenv, INI section)
}

type EndpointPolicy struct {
	// SelfHosted permits any host. Correct for services deployable at an
	// arbitrary domain — Vault, Splunk, GitLab, and every vendor shipping both a
	// SaaS and an on-prem edition. Pinning suffixes for those would break real
	// customer deployments, which is why geiger has no global host allowlist.
	SelfHosted bool
	// HostSuffixes pins a SaaS-only vendor to its own domains. A data-derived
	// host must equal one of these or be a subdomain of it. Include every region
	// and government host the vendor operates: a missing suffix is a broken
	// deployment, not a safe default.
	HostSuffixes []string
}

type EndpointScoped interface {
	EndpointPolicy() EndpointPolicy
}

type Fields map[string]string

type Finding struct {
	Key   string // short stable key (identity, account, scopes, buckets, …)
	Value string // human-readable value (already redacted where needed)
	Flag  FlagLevel
	// Detail holds the full expansion behind a summarized Value (e.g. the
	// individual file paths behind "8 editor local-history snapshots"). The
	// terminal shows it only with -v; JSON always emits it. Optional.
	Detail []string
}

type FlagLevel int

type Harvested struct {
	Label string // provenance, e.g. "secretsmanager:prod/db-password"
	Value string // the extracted secret value
}

type Harvester interface {
	Harvest(ctx context.Context, c *recon.Client, t Token, f Fields) ([]Harvested, error)
}

type Module interface {
	// Name is the stable module identifier (also used for dedupe).
	Name() string
	// Authenticate performs the optional single headless token exchange.
	// Modules that need no exchange return an empty Token and nil error.
	Authenticate(ctx context.Context, c *recon.Client, f Fields) (Token, error)
	// Recon runs the read-only recipe and returns findings.
	Recon(ctx context.Context, c *recon.Client, t Token, f Fields) ([]Finding, error)
	// Summarize turns findings into the printed Note.
	Summarize(title string, fs []Finding) Note
}

type Note struct {
	Title    string    // e.g. "GitHub PAT ghp_…JV3Q (from .env: GITHUB_TOKEN)"
	Findings []Finding // ordered lines
	Summary  string    // one-line takeaway, e.g. "org-admin bot token"
	Invalid  bool      // recon proved the credential dead/expired
	Reason   string    // why invalid, or why it could not be characterized

	// Provenance, also carried in the Title for humans. Machine formats need it
	// structurally: SARIF keys a rule off Module and a location off File/Line.
	Module string // module that characterized the credential, e.g. "aws"
	File   string // source the credential came from (path, URL, or "environment")
	Line   int    // 1-based line within File, 0 when unknown
	// Fingerprint is an upstream scanner's id for the finding this came from,
	// passed through verbatim so their viewer can dedupe against their own.
	Fingerprint string

	// Undetermined marks a credential geiger tried to characterize and could
	// not — the host was unreachable, the format has no module to exercise, a
	// passphrase is missing. It is NOT dead (nothing disproved it) and it has no
	// demonstrated reach, so scoring it from descriptive findings alone would
	// invent a severity. Set it and the tier reads UNKNOWN, with Reason saying
	// why.
	Undetermined bool
}

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

type SourceKind string

type Token struct {
	Bearer      string
	InstanceURL string            // e.g. Salesforce instance_url
	Extra       map[string]string // grant-specific extras (scope, expiry, …)
}