Takım Bilgi Tabanınızı Güvenli Hale Getirmenin Yolu API Katmanıdır

Kurumsal hafızalar dijitalleşirken, ekiplerin bilgiye hızlı ve güvenli erişimi kritik önem taşıyor. Birden fazla kişi tarafından kullanılan bilgi tabanlarında, basit bir paylaşılan API anahtarı yeterli olmayabiliyor. intent-brain adlı bu sistem, takımın kodlama ortamında doğrudan sorgulayabileceği bir bilgi deposu olarak tasarlandı. Ancak, çok kullanıcılı ortamlarda güvenlik ve denetim sorunları ortaya çıktı. Bu sorunların temelinde, paylaşılan kimliklerin yetersizliği yatıyordu. Nihayetinde, çözüm API katmanında gizliydi.

Paylaşılan Anahtarların Sınırları: Neden Kullanıcı Bazlı Kimliklere Geçilmeli?

Ekip üyeleri, qmd:// formatındaki referanslarla birlikte, kod yazarken aynı ortamda bilgi sorgulayabildikleri intent-brain sistemini kullanıyordu. Ancak, sistem tek bir TEAMKB_API_KEY ile çalışıyordu. Bu yaklaşımın iki temel sorunu vardı:

• Kimlik belirsizliği: Tüm istekler aynı kimlik üzerinden yapıldığından, kimin ne yaptığı izlenemez hale geliyordu.
• Dönüşüm zorluğu: Bir kullanıcının erişimini iptal etmek için tüm takımın anahtarını değiştirmek gerekiyordu, bu da operasyonel bir kabusa dönüşüyordu.

Bu sorunlar, yapısal bir eksiklikten kaynaklanıyordu ve kod düzeltmeleriyle giderilemeyecek nitelikteydi. Çözüm, her kullanıcıya özel tokenler atamaktan geçiyordu. Bu yaklaşım, hem kimlik doğrulamayı hem de erişim kontrolünü kişiselleştiriyor, aynı zamanda denetim süreçlerini de kolaylaştırıyordu.

Kullanıcı Özel Tokenleri: Kimliği Doğrulamanın Yeni Yolu

Sistemin apps/api/src/auth/token-registry.ts dosyasında yer alan token kayıt sistemi, her tokenın arkasındaki kullanıcıyı ve rolünü tanımlıyor. Token kayıtları aşağıdaki sırayla belirleniyor:

• Öncelikle, açık kayıtlar (explicit records)
• Ardından, TEAMKB_TOKENS JSON ortam değişkeni
• Son olarak, TEAMKB_TOKENS_FILE dosyası (varsayılan olarak ~/.teamkb/tokens.json)

Eğer hiçbir kayıt bulunmazsa, sistem varsayılan olarak TEAMKB_API_KEY kullanıyor ve bu anahtarı "shared" adlı bir admin kullanıcısına atıyor. Bu sayede, eski sistemlerle geriye dönük uyumluluk sağlanıyor. Her kayıt, actor ve role ('admin' ya da 'member') alanlarını içeriyor. Rolü belirtilmeyen kayıtlar varsayılan olarak member olarak kabul ediliyor, bu da en az ayrıcalık prensibine uygun bir tasarım sağlıyor.

Geliştirme ortamında, kayıt sistemi boş bırakılabiliyor ve tüm istekler varsayılan olarak dev kullanıcısı olarak çalıştırılıyor. Üretim ortamında ise kayıt sistemi boş bırakılamıyor ve boş kayıt sistemi kapalı kalma prensibine göre çalışıyor.

Token kayıt sistemi, güvenlik açıklarına karşı da koruma sağlıyor. Karşılaştırma işlemleri sabit zamanda (timingSafeStrEq) gerçekleştirilerek, yanıt süresinden token içeriğinin tahmin edilmesi engelleniyor. Ayrıca, token çözümleme işlemi tüm kayıtlar üzerinde tam bir tarama yapıyor. Bu sayede, yanıt süresi hangi tokenın eşleştiğine bağlı olarak değişmiyor ve saldırganlar için bilgi sızdırma olasılığı ortadan kalkıyor.

Sunucu Tarafında Yazma Koruması: Yetkilendirmenin Temeli

Sistemin apps/api/src/middleware/write-gate.ts dosyasında yer alan yazma koruma mekanizması, admin olmayan kullanıcıların belirli işlemleri gerçekleştirmesini engelliyor. Bu koruma, Fastify'nin onRequest kancası aracılığıyla uygulanıyor ve kimlik doğrulamasından sonra çalışıyor.

Yazma korumasının uygulandığı yol önekleri ve HTTP yöntemleri aşağıdaki gibidir:

• /api/memories
• /api/policies
• /api/import

Sadece POST, PUT, PATCH ve DELETE yöntemleriyle yapılan istekler bu korumadan geçmek zorunda. Diğer yöntemler (örneğin GET) doğrudan erişime izin veriyor. Bu sayede, üyeler bilgileri okuyabilir ve önerilerde bulunabilir, ancak bilgileri yayınlama, politika düzenleme veya toplu ithal etme gibi işlemler için admin yetkisi gerekiyor.

MCP Sunucusu: Kullanıcı Deneyimi mi, Güvenlik mi?

MCP sunucusu apps/mcp-server/src/server.ts dosyasında yer alıyor ve okuyucu araçlarını (örneğin teamkb_search, teamkb_status, teamkb_neighbors) her zaman kaydediyor. Yazma araçları ise sadece admin kurulumlarında kaydediliyor. Bu kayıt işlemi, sistemin zaten kullanmakta olduğu withSync bayrağından esinlenerek tasarlanıyor. Bu sayede, yeteneklerin kullanılabilirliği doğrudan araç kayıtlarına yansıyor.

Ancak, MCP sunucusundaki bu koruma mekanizması aslında kullanıcı deneyimi odaklıdır. Güvenlik, esas olarak API katmanında uygulanıyor. MCP sunucusu, sadece kullanıcı dostu bir arayüz sunarken, gerçek güvenlik katmanı API seviyesinde yer alıyor. Bu yaklaşım, sistemin hem kullanım kolaylığı hem de güvenlik açısından dengeli bir yapıya sahip olmasını sağlıyor.

Geleceğe Bakış: Sürekli Güvenlik ve Denetim

Günümüzde, takım içi bilgi paylaşımında güvenlik ve denetim artık lüks değil, zorunluluk haline geldi. intent-brain sistemi, API katmanında uygulanan kimlik ve yetkilendirme mekanizmalarıyla, ekiplerin bilgiye erişimini hem güvenli hem de verimli hale getiriyor. Gelecekte, bu tür sistemlerin daha da yaygınlaşması ve gelişmiş yapay zeka entegrasyonlarıyla birlikte, kurumsal hafızaların yönetimi daha da akıllı ve güvenilir hale gelecek. Güvenlik ve kullanım kolaylığı arasındaki dengeyi korumak, dijital dönüşümün vazgeçilmez bir parçası olmaya devam edecek.