Kavramlar

Kit

Kit, Ketvia’nın Slack uygulamalarına karşılık gelen yapısıdır. Genel bir kimliği (bir id ve bir slug) vardır ve bir manifestle tanımlanır. Kit’in kodu geliştiricinin kendi sunucularında çalışır; Ketvia bu kodu hiçbir zaman barındırmaz ya da çalıştırmaz.

Kit’lerin bir dağıtım biçimi vardır:

Dağıtım	Anlamı	Durum
private	Bir çalışma alanının yöneticisi oluşturur ve yalnızca orada kurulur.	Şimdi
unlisted	Kurulum bağlantısına sahip her çalışma alanı kurabilir.	Sonraki aşama
directory	İncelenir ve Kit dizininde listelenir.	Sonraki aşama

Manifest

Manifest, Kit’in ne olduğunu ve neler yapabileceğini bildiren JSON belgesidir: adları, geliştiricisi, botunun ve kullanıcılarının alabileceği kapsamlar, gelen webhook’lar ve OAuth yönlendirme adresleri. Bir onay belgesi olduğu için katıdır: bilinmeyen anahtarlar reddedilir, adresler https olmalıdır, görünen metinler yerelleştirilir (en zorunlu, tr isteğe bağlı).

Her manifestin bir version değeri vardır (major.minor.patch). Aynı slug’ı daha yüksek bir sürümle yüklemek Kit’i günceller ve çalışma alanındaki kurulum yeni sürüme geçer. Bkz. manifest başvurusu.

Kurulum

Kurulum, bir Kit sürümünün bir çalışma alanına kurulmuş halidir. Kit botu, o çalışma alanında Kit için verilen token’lar ve gelen webhook’lar kuruluma aittir. Bir kurulum her zaman tek bir çalışma alanına aittir; bir token hiçbir zaman başka bir çalışma alanına ulaşamaz.

Kit’i kurmak tek başına hiçbir şeyi açmaz: bir yönetici Kit botunu bir kanala ekleyene kadar bot hiçbir kanalı görmez ve biri oluşturulmadan ya da yetkilendirilmeden hiçbir token yoktur.

Kit botu ve asistanlar

Bot kapsamı isteyen her kurulumun bir Kit botu vardır: Kit’in mesajlarının yazarı olan kimlik. Kit botu bir asistan değildir. Ketvia’nın asistanları, kendi talimatları ve izinleri olan yapay zekâ botlarıdır; Kit botu hiçbir zaman model çalıştırmaz ve soru yanıtlamaz. Yalnızca Kit’in kodunun Web API ya da webhook üzerinden yaptığını yapar.

Kit botu yalnızca eklendiği kanallarda çalışır. Yöneticiler onu Kit’in API erişimi sayfasından ve yalnızca kendilerinin üyesi olduğu kanallara ekler. Bir kanal için gelen webhook oluşturmak da Kit botunu o kanala ekler.

Bot token’ları ve kullanıcı token’ları

	Bot token’ı (kbot_…)	Kullanıcı token’ı (kusr_…)
Kimin adına	Kit botu	Tek bir üye
Neyi görür	Yalnızca Kit botunun eklendiği kanalları	O üyenin görebildiklerini
Düzenler/siler	Yalnızca kendi mesajlarını	Yalnızca o üyenin mesajlarını
Kapsamlar	Manifestteki bot.scopes	Manifestteki userScopes
Süre	Süresiz; yenilenir ya da iptal edilir	1 saat; tek kullanımlık yenileme token’ı ile uzatılır
Nasıl alınır	API erişimi sayfasında yönetici, ya da kit.access (bot)	Üyenin kit.access (kullanıcı, PKCE ile) akışında izin vermesi

Kullanıcı token’ı, onu yetkilendiren üyenin web oturumu sona erdiğinde de sona erer. v1’de bazı işlemler yalnızca kullanıcılar içindir: Kit botları henüz tepki ekleyemez ve dosya yükleyemez; bunlar için kullanıcı token’ı kullanın. Bkz. Token’lar ve kimlik doğrulama.

Kapsamlar

Kapsam, messages:write gibi bir izin metnidir. Bir token yalnızca kapsamına sahip olduğu metotları çağırabilir ve kurulu manifest sürümünün istediğinden fazlasını hiçbir zaman alamaz. Bot ve kullanıcı kapsamları ayrıdır. Bir kapsam üyeliği aşmaz: bot token’ındaki messages:read yalnızca Kit botunun eklendiği kanalları okur.

Bilerek hiçbir yönetici kapsamı yoktur: bir Kit üyeleri ya da kanalları yönetemez, denetim kaydını okuyamaz, hiçbir şeyi onaylayamaz. Bkz. Kapsamlar.

Onay

Her erişim açık bir insan kararıdır:

• Bir yönetici özel Kit’i manifestinden oluşturur ve kurar. Manifestteki kapsamlar, Kit’in o çalışma alanında alabileceğinin en fazlasıdır.
• Bir yönetici Kit botunu kanallara ekler, bot token’ları ve gelen webhook’lar oluşturur.
• Kullanıcı token’larında her üye, Ketvia’nın yetkilendirme sayfasında kendisi karar verir; token o üyenin kendi erişimiyle sınırlıdır.

İptal

İptal anında geçerlidir:

• İptal edilen bir bot token’ı hemen çalışmayı bırakır (401 invalid_token).
• İptal edilen bir gelen webhook hemen 404 döndürür.
• Bir kapsamı kaldıran yeni manifest sürümü, mevcut token’ları hemen daraltır.
• Bir kullanıcı yenileme token’ını ikinci kez kullanmak tüm yetkiyi (erişim ve yenileme token’ları) iptal eder.
• Kit’i kaldırmak tüm token’larını iptal eder ve webhook’larını devre dışı bırakır.

Güvenlik modeli

• Gizli değerler bir kez gösterilir ve özetleri saklanır. Bot token’ları, kullanıcı token’ları, yenileme token’ları, istemci gizli anahtarları ve webhook adreslerinin gizli kısmı yalnızca onları oluşturan yanıtta görünür. Ketvia yalnızca özetini (hash) saklar; kaybolan bir gizli değer geri getirilmez, yenisiyle değiştirilir.
• Göremediğiniz her şey için 403 değil 404. Bir konuşmayı, mesajı, dosyayı ya da üyeyi görme izni olmayan token, o şey hiç yokmuş gibi 404 not_found alır. 403 yalnızca token’ın ne olduğuyla ilgilidir (eksik kapsam ya da bu işi yapamayan token türü); bir şeyin var olup olmadığını hiçbir zaman belli etmez.
• Çalışma alanı yalıtımı. Çalışma alanı token’dan anlaşılır. Her sorgu, veritabanının satır düzeyi güvenliğiyle o çalışma alanına bağlıdır; hiçbir istek parametresi başka bir çalışma alanına ulaşamaz.
• Yapay zekâ modeline veri gitmez. Bir Kit’in Web API ya da webhook üzerinden okuduğu veya yazdığı hiçbir şey, Kit adına Ketvia’nın dil modeline gönderilmez; özel asistan sonuçları Web API’den hiçbir zaman dönmez.
• Mesajlarda uzak içerik yok. Blocks uzak görsel yükleyemez; görsel blokları yalnızca Ketvia dosyalarına işaret eder.

Sıradaki: kendi Kit’iniz için güvenlik kontrol listesi.