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 ¶
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 ¶
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 ¶
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 ¶
MaskedAPIKeyName returns the non-secret identifier for an API key.
func ResourceOwnerID ¶
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 ¶
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.