providerpolicy

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

type Config struct {
	// ProviderKey names the provider in error messages ("github", "hubspot").
	ProviderKey string
	// SnapshotEndpoint is the cloud path serving the policy snapshot. Tenancy
	// is resolved from the install token; missing/unknown/revoked tokens get
	// 401.
	SnapshotEndpoint string
	// RequestSchema is the schema version to request via `?schema=`; empty
	// omits the parameter.
	RequestSchema string
	// Schemas lists the accepted wire-format versions, most preferred first.
	Schemas []SchemaSupport
	// CacheFileName is the snapshot's on-disk name next to the guard DB.
	CacheFileName string
	// CacheTempPattern is the os.CreateTemp pattern for atomic persistence.
	CacheTempPattern string
	// RefreshEnvVar optionally overrides the refresh interval.
	RefreshEnvVar string
}

type EndpointDirectory struct {
	InstallationID  string   `json:"installationId"`
	DirectoryUserID *string  `json:"directoryUserId"`
	GroupIDs        []string `json:"groupIds"`
}

type Evaluation struct {
	Request      Request
	Result       string // "allow" | "deny"
	ReasonCode   string
	Reason       string
	MatchedRules []MatchedRule
	// DecidingRuleID is the rule that determined the outcome: the first
	// matching deny, or the org-layer allow that anchored an allow. Empty
	// when a layer vetoed by silence.
	DecidingRuleID string
	Mode           string
	Epoch          int
	Hash           string
	// Stale is true when the snapshot used was not confirmed by the cloud on
	// the most recent refresh attempt.
	Stale bool
	// SubjectsResolved is false when no Kontext user/application identity was
	// available, so user/agent-layer rules could not match their subject.
	SubjectsResolved bool
	// GroupsResolved is true when this endpoint's directory identity was
	// resolved to a user (even one with zero group memberships). False means
	// group-layer rules could not have matched for identity reasons: v2
	// snapshot, no installation id sent, directory for another endpoint, or
	// a missing/unmatched/ambiguous email.
	GroupsResolved bool
	// SchemaVersion is the wire format of the snapshot that produced this
	// evaluation (v2 or v3 during the negotiation window).
	SchemaVersion string
}

type MatchedRule struct {
	ID      string `json:"id"`
	Layer   string `json:"layer"`
	Effect  string `json:"effect"`
	Decided bool   `json:"decided,omitempty"`
}

type Request struct {
	Action        string
	Resource      string
	BranchOrRef   string
	UserID        string
	ApplicationID string
	EndpointID    string
}

type Rule struct {
	ID    string `json:"id"`
	Layer string `json:"layer"`
	// SubjectID is the org id, kontext user id, application id, endpoint
	// installation id, or directory group uuid depending on Layer.
	SubjectID string `json:"subjectId"`
	// ResourceID is the provider resource anchor, or nil for any resource.
	ResourceID *string `json:"resourceId"`
	// ActionName is a canonical action name (e.g. "github.pr.write",
	// "hubspot.object.write"), or nil for any action.
	ActionName *string `json:"actionName"`
	// BranchOrRef is a branch or ref constraint, or nil for any branch.
	BranchOrRef *string `json:"branchOrRef"`
	Effect      string  `json:"effect"`
	// Specificity is a diagnostic hint the cloud computes for display/sorting.
	// The evaluator does not read it: it derives precedence from the rule's
	// own dimensions and layer (see Evaluate — most-specific-wins).
	Specificity int `json:"specificity"`
}

type SchemaSupport struct {
	Version string
	// GroupLayer is true when rules in this version may carry layer=group.
	// A group rule in a version without it is server misbehavior.
	GroupLayer bool
	// Directory is true when a server answering this version must echo the
	// endpointDirectory block whenever the request identified the endpoint.
	// Its absence would silently strip group-layer carve-out denies while
	// keeping broader allows.
	Directory bool
}

type Snapshot struct {
	SchemaVersion  string `json:"schemaVersion"`
	OrganizationID string `json:"organizationId"`
	// ProviderID is the provider row id, or nil when the org's policy is
	// key-only.
	ProviderID  *string `json:"providerId"`
	ProviderKey string  `json:"providerKey"`
	Mode        string  `json:"mode"`
	// Epoch is the active policy epoch; 0 when the org has no active policy.
	Epoch int `json:"epoch"`
	// Hash is a stable content hash over the epoch, rules, and (when the
	// contract carries one) the endpoint directory — a directory membership
	// change changes the hash. Independent of GeneratedAt, so an unchanged
	// policy keeps an unchanged hash.
	Hash  string `json:"hash"`
	Rules []Rule `json:"rules"`
	// PayloadCaptureMode is the org's tool-payload capture directive
	// ("omitted" | "summary" | "full"). Absent on pre-capture servers and on
	// providers that do not carry it (the github snapshot is authoritative).
	// Deliberately EXCLUDED from Hash (server-side decision), so a mode
	// flip arrives on a snapshot whose hash is unchanged — consumers must
	// not gate mode application on hash inequality (see Cache.Apply).
	// Normalize via payloadcapture.NormalizeMode; unknown values fall back
	// to "summary" (never capture on an unrecognized directive).
	PayloadCaptureMode string `json:"payloadCaptureMode,omitempty"`
	// EndpointDirectory is this endpoint's resolved directory identity (nil
	// on versions without directory support or when the request carried no
	// installation id).
	EndpointDirectory *EndpointDirectory `json:"endpointDirectory,omitempty"`
	GeneratedAt       string             `json:"generatedAt"`
}

type SnapshotProvider interface {
	CurrentSnapshot() (Snapshot, Status, bool)
}

type Status struct {
	// FetchedAt is when the cached snapshot was last confirmed by the cloud
	// (fetch succeeded, whether or not the hash changed).
	FetchedAt time.Time `json:"fetched_at"`
	// Stale is true when the most recent fetch attempt failed and the cache
	// is serving the last known snapshot.
	Stale bool `json:"stale"`
	// LastError holds the most recent fetch failure, if any.
	LastError string `json:"last_error,omitempty"`
}