Method principalFromOAuthToken

internal/agent/api.go:745–809

principalFromOAuthToken validates an ate2a_-prefixed bearer via fosite's IntrospectToken (which derives the signature using the same strategy that issued the token, looks up the row via our Storage, and checks revoked/expired) and resolves it to a SCOPED principal. The granted OAuth scope is author

(r *http.Request, bearer string)

// Every failure wraps errOAuthBearerInvalid so the response layer reliably
// classifies these as OAuth-bearer rejections and emits the OAuth challenge.
func (a *API) principalFromOAuthToken(r *http.Request, bearer string) (*identity.Principal, error) {
	if a.oauthProvider == nil {
		// OAuth not enabled on this deployment. Fail closed rather
		// than fall through to the API-key path (which would compare
		// the ate2a_ token against the api_keys hash and miss — a
		// slower path to the same 401, with a less actionable log).
		return nil, fmt.Errorf("%w: provider not configured", errOAuthBearerInvalid)
	}
	session := &oauth.Session{}
	tu, ar, err := a.oauthProvider.IntrospectToken(r.Context(), bearer, fosite.AccessToken, session)
	if err != nil {
		// Preserve fosite's typed error via %w so writeAuthError can
		// errors.Is(...) against fosite.ErrTokenExpired below.
		return nil, fmt.Errorf("%w: %w", errOAuthBearerInvalid, err)
	}
	// Defense in depth: fosite v0.49's IntrospectToken with
	// tokenUse=AccessToken doesn't HARD-reject a refresh-token row —
	// it falls back to refresh-token validation if access fails. We
	// rely on table separation in storage to keep them disjoint, but
	// an explicit check at the seam means a future fosite/storage
	// refactor can't silently break the type guard.
	if tu != fosite.AccessToken {
		return nil, fmt.Errorf("%w: token is not an access token (got %q)", errOAuthBearerInvalid, tu)
	}
	// Trust the session, not the request — the session was loaded
	// from the DB row fosite hydrated.
	sess, ok := ar.GetSession().(*oauth.Session)
	if !ok || sess.UserID == "" {
		return nil, fmt.Errorf("%w: session missing user_id", errOAuthBearerInvalid)
	}
	u, err := a.store.GetUserByID(r.Context(), sess.UserID)
	if err != nil {
		// Wrap so writeAuthError emits the OAuth challenge instead of
		// a bare 401 (the bearer that got us here was valid; the user
		// row vanished out from under it).
		return nil, fmt.Errorf("%w: user lookup: %v", errOAuthBearerInvalid, err)
	}

	granted := ar.GetGrantedScopes()
	switch {
	case granted.Has(identity.ScopeAccount):
		return &identity.Principal{User: u, Scope: identity.ScopeAccount}, nil
	case granted.Has(identity.ScopeAgent):
		// Confine to the consent-bound agent. An agent-scoped token with no
		// bound agent is malformed — reject rather than fall back to anything
		// broader.
		if sess.AgentEmail == "" {
			return nil, fmt.Errorf("%w: agent-scoped token has no bound agent", errOAuthBearerInvalid)
		}
		ag, err := a.store.GetAgentByEmail(r.Context(), identity.NormalizeEmail(sess.AgentEmail))
		if err != nil || ag == nil {
			return nil, fmt.Errorf("%w: bound agent not found", errOAuthBearerInvalid)
		}
		// Ownership re-check: the bound agent must still belong to the token's
		// user (defends against an agent reassigned/deleted-and-recreated under
		// a different owner after consent).
		if ag.UserID != u.ID {
			return nil, fmt.Errorf("%w: bound agent not owned by token user", errOAuthBearerInvalid)