principal

package
v0.26.2 Latest Latest
Warning

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

Go to latest
Published: Oct 2, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package principal interprets who an authenticated caller is.

Obot authenticates people and hosted agents. They are not interchangeable: an agent authenticates as itself so that a compromised sandbox reaches only what that one instance was configured with, which means its identity is an instance rather than a row in the users table. Code that needs "the user who owns this" therefore cannot use the caller's ID directly.

Index

Constants

View Source
const (
	// HostedAgentOwnerExtra carries the user a hosted agent was created by. It is
	// set on the principal at authentication time.
	HostedAgentOwnerExtra = "hosted_agent_owner_id"

	// AuthorizedModelIDsExtra carries the Model resource names a hosted agent was
	// configured with, or "*" for every model. It is the agent's whole authority
	// over models: an agent is not re-evaluated against access policies, which
	// describe people.
	AuthorizedModelIDsExtra = "authorized_model_ids"

	// APIKeyIDExtra and APIKeyNameExtra carry the non-secret credential
	// attribution established by the API-key authenticator. Downstream code
	// must use APIKeyAttributionFromUser instead of interpreting these values.
	APIKeyIDExtra   = "api_key_id"
	APIKeyNameExtra = "api_key_name"
)

Variables

This section is empty.

Functions

func AuthorizedModelIDs

func AuthorizedModelIDs(user kuser.Info) ([]string, bool)

AuthorizedModelIDs returns the models a hosted agent may use, and whether the caller is an agent at all.

Every caller that carries the extra is an agent, but the reverse does not hold: an agent configured with no models has none, which is an empty list and not the absence of one. Callers must distinguish those, because an agent authorized for nothing may use nothing, while a person is governed by policy instead.

func IsHostedAgent

func IsHostedAgent(user kuser.Info) bool

IsHostedAgent reports whether a caller is a sandbox rather than a person.

The owner extra is the marker rather than a group of its own. A sandbox's groups say what it may reach -- models, MCP servers, skills -- and those are the same groups a person can hold, so they cannot answer what it is. Only a sandbox is issued on behalf of someone else, which is exactly what this extra records, and ResourceOwnerID already relies on it being set.

func MaskedAPIKeyName

func MaskedAPIKeyName(userID string, keyID uint) string

MaskedAPIKeyName returns the non-secret identifier for an API key.

func ResourceOwnerID

func ResourceOwnerID(user kuser.Info) string

ResourceOwnerID returns the user that owns what a caller creates, and that usage is attributed to.

For a person this is their own ID. For a hosted agent it is the user who created it, because the resources an agent touches belong to that person and the usage it incurs is theirs. Using the agent's own ID here produces records pointing at a user that does not exist, which fails lookups and, in a controller, requeues forever.

This is distinct from authorization, which uses the caller's real identity: an agent may only reach what its own configuration allows, regardless of what its owner can reach.

Types

type APIKeyAttribution

type APIKeyAttribution struct {
	ID   uint
	Name string
}

APIKeyAttribution identifies the API key that authenticated a request.

func APIKeyAttributionFromUser

func APIKeyAttributionFromUser(user kuser.Info) (APIKeyAttribution, bool)

APIKeyAttributionFromUser returns the API key that authenticated a caller. A missing or malformed ID means the caller did not authenticate with an API key. The authenticator supplies a display name, including the masked fallback for an unnamed key; an empty name indicates a legacy or malformed principal.

func NewAPIKeyAttribution

func NewAPIKeyAttribution(id, ownerUserID uint, name string) APIKeyAttribution

NewAPIKeyAttribution creates event-time display attribution for an API key. Unnamed keys use the reconstructable, non-secret masked key identifier so audit consumers never need to join back to the API-key table to label them.

Jump to

Keyboard shortcuts

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