botidentity

package
v0.56.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

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

View Source
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

View Source
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

type BotRoleQuery struct {
	Forge  string
	Target string
	Login  string
}

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

type MintBotRoleRequest struct {
	ActorLogin string `json:"actor_login"`
	Repo       string `json:"repo"`
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL