Headless Sunucuda Higgsfield CLI Girişi: localhost Tuzağı
OAuth PKCE tabanlı CLI girişleri headless sunucularda neden başarısız olur? localhost'un makineye özel olması, redirect URI allowlist'i ve callback URL'ini elle taşıma çözümü.
Higgsfield CLI'ı bir sunucuya kurup giriş yapmaya çalışırken klasik bir OAuth 2.0 PKCE sorunuyla karşılaşılıyor: CLI, localhost üzerinde bir HTTP dinleyici açıp tarayıcıdan gelecek callback'i bekliyor. Ancak sunucu headless olduğu için tarayıcı laptop'ta, dinleyici sunucuda çalışıyor; Clerk'in yönlendirdiği localhost adresi iki farklı makineyi işaret ediyor ve bağlantı başarısız oluyor. Bu, aracın hatası değil, loopback OAuth akışının tarayıcı ile dinleyicinin aynı makinede olduğunu varsaymasından kaynaklanıyor.
SSH tüneli klasik çözüm olsa da, --port bayrağıyla portu sabitlemeye çalışmak Clerk'in 'redirect_uri eşleşmiyor' hatasına takılıyor; çünkü PKCE istemci sırrını kaldırsa da sağlayıcının önceden kayıtlı redirect URI allowlist'ini korumaya devam ediyor. Yani port serbestçe seçilemiyor, sadece uygulamanın kayıtlı portlarından biri kullanılabiliyor.
Asıl çözüm, callback'in aslında sadece code ve state parametrelerini taşıyan düz bir HTTP GET isteği olduğunu fark etmekten geçiyor. Tarayıcıda 'Unable to connect' hatası alındıktan sonra adres çubuğundaki URL kopyalanıp sunucuda curl ile doğrudan dinleyiciye gönderiliyor; dinleyici state eşleşmesini doğrulayıp kodu token'a çeviriyor ve giriş tamamlanıyor. Bu yöntem, state parametresinin sahtecilik önleme kontrolünü zaten karşıladığı için güvenlik açığı değil, akışın kendi tasarımının bir uzantısı oluyor.
Bu yazı, headless makinelerde loopback redirect kullanan herhangi bir CLI için (ki günümüzde çoğu böyle) genelleştirilebilir bir pratik sunuyor: tünel kurmak yerine callback URL'ini elle taşımak, hem daha az hareketli parça hem de aynı güvenlik garantisi anlamına geliyor.