mgmt

type Actor ¶

type Actor struct {
	Email string
	Name  string

	// Synthetic is true when Email was derived from $USER@host instead of
	// a real git config value. Synthetic actors cannot pass mgmt
	// mutations because their identity can be spoofed by flipping $USER;
	// see RequireRealIdentity.
	Synthetic bool

	// Bot is non-empty when the caller is acting as a bot (typically via
	// SX_BOT=<name>). Email is then "bot:<name>" so audit attribution
	// stays unique and never collides with a human email. See IsBot.
	Bot string
}

Actor is a resolved caller identity used for audit, usage, and install targeting.

func CurrentGitActor(ctx context.Context, repoPath string) (Actor, error)

func (a Actor) IsBot() bool

func (a Actor) RequireRealIdentity() error

func (a Actor) String() string

type ActorUsageCount ¶

type ActorUsageCount struct {
	Actor     string
	TotalUses int
}

ActorUsageCount is the per-actor rollup in a UsageSummary.

type AssetUsageCount ¶

type AssetUsageCount struct {
	AssetName    string
	AssetType    string
	TotalUses    int
	UniqueActors int
	LastUsed     time.Time
}

AssetUsageCount is the per-asset rollup in a UsageSummary.

type AuditEvent ¶

type AuditEvent struct {
	Timestamp  time.Time      `json:"ts"`
	Actor      string         `json:"actor"`
	Event      string         `json:"event"`
	TargetType string         `json:"target_type"`
	Target     string         `json:"target"`
	Data       map[string]any `json:"data,omitempty"`
}

AuditEvent is a single row in .sx/audit/YYYY-MM.jsonl.

func QueryAuditEvents(vaultRoot string, filter AuditFilter) ([]AuditEvent, error)

type AuditFilter ¶

type AuditFilter struct {
	Actor       string
	EventPrefix string
	Target      string
	Since       time.Time
	Until       time.Time
	Limit       int
}

AuditFilter narrows an audit query. Zero values mean "don't filter on that field". EventPrefix matches if the event string starts with the prefix (e.g. "team." matches every team event).

type Bot ¶ added in v1.0.0

type Bot struct {
	Name        string
	Description string
	Teams       []string
}

Bot is a non-human service identity that consumes assets. Bots gain repository context by being members of one or more teams; assets can also be installed directly to a bot via the InstallKindBot scope.

File-based vaults (path/git) treat bots as identity-only — the trust boundary is "vault read access ⇒ asset access", so anyone with access to the vault can claim any bot identity by setting SX_BOT=<name>. Sleuth vaults issue real OAuth API keys via createBotApiKey; that capability is exposed only on the BotApiKeyManager interface.

func (b *Bot) IsOnTeam(name string) bool

type BotApiKey ¶ added in v1.0.0

type BotApiKey struct {
	ID          string
	Label       string
	MaskedToken string
	CreatedAt   time.Time
}

BotApiKey is metadata about a bot API key, returned by Sleuth vaults. The raw token is only available at creation time. File-based vaults don't issue keys, so callers should expect ErrNotImplemented from the BotApiKeyManager methods on those.

type Team ¶

type Team struct {
	Name         string   `toml:"name"`
	Description  string   `toml:"description,omitempty"`
	Members      []string `toml:"members,omitempty"`
	Admins       []string `toml:"admins,omitempty"`
	Repositories []string `toml:"repositories,omitempty"`
}

Team is a named grouping of members, admins, and repositories. It is the unit of targeted installation for git and path vaults and the shape returned by the Vault interface's team-management methods.

func (t *Team) IsAdmin(email string) bool

func (t *Team) IsMember(email string) bool

type UsageEvent ¶

type UsageEvent struct {
	Timestamp    time.Time `json:"ts"`
	Actor        string    `json:"actor"`
	AssetName    string    `json:"asset_name"`
	AssetVersion string    `json:"asset_version"`
	AssetType    string    `json:"asset_type"`
}

UsageEvent is a single row in .sx/usage/YYYY-MM.jsonl. Timestamp and actor are normalized to UTC and lowercase respectively at append time.

func ReadUsageEvents(vaultRoot string, filter UsageFilter) ([]UsageEvent, error)

type UsageFilter ¶

type UsageFilter struct {
	AssetName string
	AssetType string
	Actor     string
	Since     time.Time
	Until     time.Time
}

UsageFilter narrows a usage query.

type UsageSummary ¶

type UsageSummary struct {
	TotalEvents int
	PerAsset    []AssetUsageCount
	PerActor    []ActorUsageCount
}

UsageSummary is the aggregated result of a usage query.

func SummarizeUsage(vaultRoot string, filter UsageFilter) (*UsageSummary, error)