Method GetPrincipalByAPIKey

internal/identity/store.go:3525–3549

GetPrincipalByAPIKey authenticates a bearer token and returns the full principal — the owning user PLUS the key's scope and bound agent (Slice 5a). Same validation/last_used semantics as GetUserByAPIKey (it delegates here). A legacy key with a NULL scope column resolves to ScopeAccount, preserving p

(ctx context.Context, apiKey string)

// A legacy key with a NULL scope column resolves to ScopeAccount, preserving
// pre-redesign authority.
func (s *Store) GetPrincipalByAPIKey(ctx context.Context, apiKey string) (*Principal, error) {
	keyHash := hashAPIKey(apiKey)
	u := &User{}
	var scope string
	var agentID *string
	err := s.pool.QueryRow(ctx,
		`WITH touched AS (
		   UPDATE api_keys SET last_used_at = now()
		   WHERE key_hash = $1
		     AND revoked_at IS NULL
		     AND (expires_at IS NULL OR expires_at > now())
		   RETURNING user_id, COALESCE(scope, 'account') AS scope, agent_id
		 )
		 SELECT u.id, u.email, u.name, u.google_subject, u.created_at, t.scope, t.agent_id
		 FROM touched t JOIN users u ON u.id = t.user_id`, keyHash,
	).Scan(&u.ID, &u.Email, &u.Name, &u.GoogleSubject, &u.CreatedAt, &scope, &agentID)
	if err != nil {
		return nil, err
	}
	p := &Principal{User: u, Scope: scope}
	if agentID != nil {
		p.AgentID = *agentID
	}
	return p, nil
}

func generateID() string {
	b := make([]byte, 16)