Documentation
¶
Overview ¶
Package botidentity resolves the provider-registered Fullsend identity of bot actors (ADR 0107). It holds the forge-neutral contract the dispatch path and the behaviour tests share; provider clients implement it.
The package is named for bot identity management in general: bot-role lookup is its first concern, and other identity operations (such as credential retrieval) may join it later. It must not import internal/mintcore, so pkg/behaviourtest can use it.
Index ¶
Constants ¶
const ( MintBotRolePath = "/v1/bot-role" MintOutcomeRecognized = "recognized" MintOutcomeNoMatch = "no_match" )
Wire contract of the mint's GitHub bot-role lookup (POST /v1/bot-role in internal/mintcore). The mint authenticates the caller with its GitHub Actions OIDC token, binds Repo to the token's repository claim, and answers with role names only, never credentials. internal/mintcore is a separate module and duplicates these names; change both together.
Variables ¶
var ErrLookup = errors.New("bot-role lookup failed")
ErrLookup marks a bot-role lookup that did not complete: a provider, transport, authentication or protocol failure. Callers must fail closed, and must keep it distinct from a successful no-match.
Functions ¶
func ApplyBotRoleResult ¶
func ApplyBotRoleResult(actor *normevent.Actor, res BotRoleResult, lookupErr error)
ApplyBotRoleResult projects a lookup outcome onto the normalized actor fields (ADR 0107): the actor is a bot with actor.role "none"; a recognized role sets actor.bot_role; actor.role_verified is true for a completed lookup (recognized or no-match) and false for a failure, which never carries a bot_role.
Types ¶
type BotRoleQuery ¶
BotRoleQuery identifies the bot whose registered role is looked up.
Every field comes from the verified source system: Forge is the source system ("github"), Target the repository the event belongs to ("owner/repo") and Login the verified actor login (for GitHub Apps "<slug>[bot]"). Roles or identity claims found in event content are never part of a query.
type BotRoleResolver ¶
type BotRoleResolver interface {
ResolveBotRole(ctx context.Context, q BotRoleQuery) (BotRoleResult, error)
}
BotRoleResolver resolves a verified bot identity to its registered Fullsend role for one target. A nil error with an empty Role is a successful no-match; any error is a lookup failure and wraps ErrLookup.
type BotRoleResult ¶
type BotRoleResult struct {
Role string
}
BotRoleResult is a completed lookup. Role is the canonical Fullsend role of a recognized bot, or empty for a successful no-match.
func ParseMintBotRoleResponse ¶
func ParseMintBotRoleResponse(status int, body []byte) (BotRoleResult, error)
ParseMintBotRoleResponse maps a mint answer to a lookup outcome. Only a 200 with a well-formed outcome is a completed lookup; every other status or body is a lookup failure wrapping ErrLookup, so a failure can never read as a successful no-match.
func (BotRoleResult) Recognized ¶
func (r BotRoleResult) Recognized() bool
Recognized reports whether the lookup matched a registered role.
type MintBotRoleRequest ¶
MintBotRoleRequest is the JSON body of POST /v1/bot-role.
type MintBotRoleResponse ¶
type MintBotRoleResponse struct {
Outcome string `json:"outcome,omitempty"`
Role string `json:"role,omitempty"`
Error string `json:"error,omitempty"`
}
MintBotRoleResponse is the JSON body the mint answers with: a 200 carries Outcome (and Role when recognized); an error status carries Error.
type MintResolver ¶
type MintResolver struct {
// MintURL is the mint base URL.
MintURL string
// OIDCToken returns the caller's GitHub Actions OIDC token for the
// mint audience. The token's repository claim must be the query target.
OIDCToken func(ctx context.Context) (string, error)
// HTTPClient sends the request; a client with a request timeout when
// nil. The resolver always enforces its redirect policy (no
// HTTPS-to-HTTP downgrade) on top of the client's own CheckRedirect,
// and bounds every lookup by mintRequestTimeout through its request
// context.
HTTPClient *http.Client
}
MintResolver resolves GitHub bot roles through the mint's POST /v1/bot-role endpoint. It implements BotRoleResolver.
func (*MintResolver) ResolveBotRole ¶
func (m *MintResolver) ResolveBotRole(ctx context.Context, q BotRoleQuery) (BotRoleResult, error)
ResolveBotRole implements BotRoleResolver for the GitHub forge.