RBAC (rol-tabanlı yetki)

Açık çekirdek roleAuth dört SABİT sınıf verir (superAdmin/admin/client/viewer). Bu bir sınırdır, bir sözlük değil: viewer kendi organizasyonundaki her şeyi okur ve daraltılamaz. Kendi ekip rollerinize ihtiyaç duyduğunuzda (editör, denetçi, operatör) — ya da çok daha sık karşılaşılanı, birinin koşuları görmesini ama içindeki sohbetleri görmemesini istediğinizde — bunu ifade eden katman budur.

RBAC tek başına bir AuthProvider değildir — createEnterpriseAuth'a rbac seçeneği olarak verilir; kimlik doğrulama (SSO/user-store/fallback) ayrı, yetkilendirme (bu modül) ayrı adımdır.

import { createRbac, createEnterpriseAuth } from '@gnldev/auth-ee';
import type { Permission, RbacProvider } from '@gnldev/auth-ee';

@gnldev/auth-ee paralı/lisanslı bir pakettir — geçerli bir lisans anahtarı olmadan createEnterpriseAuth fallback'e (genelde açık-çekirdek roleAuth) düşer ve RBAC devreye girmez.

1. Rol→izin haritanızı tanımlayarak createRbac çağırın — izinler 'kaynak:eylem' kalıbıdır, '*' hem kaynak hem eylem tarafında joker olarak kullanılabilir:

import { createRbac, createEnterpriseAuth } from '@gnldev/auth-ee';

const rbac = createRbac({
  editor: ['runs:read', 'runs:write'],
  viewer: ['*:read'],
});

Harita verilmezse varsayılan { viewer: ["*:read"], member: ["*:read", "agents:run"], admin: ["*"], "platform-admin": ["*"] } kullanılır. Pratikte en çok işe yarayan kademe member: o olmadan birine ajan koşturma yetkisi vermek, onu admin yapmak demekti.

2. rbac'ı createEnterpriseAuth'a verin — dönen AuthProvider, REST/Studio'ya aynen auth olarak geçirilir:

const auth = createEnterpriseAuth({ licenseKey, rbac, fallback });
// authorize(principal, ctx) -> { allow: true } | { allow: false, status: 403 }

3. Principal'ın izinleri, önce doğrudan principal.permissions (varsa) üzerinden, yoksa principal.roles rollerinin haritadaki karşılıklarının birleşiminden türer. Kimliği doğrulanmamış (principal === null) istekler doğrudan 401 alır, izinsiz kalanlar 403 alır.

Yazma ekseninde hep adlandırılmış izinler vardı (agents:run, users:write, budget:write …). Okumada tek bir tane vardı — *:read — yani “destek koşuları okusun” ile “destek her müşterinin mesajını okusun” aynı karardı. Artık yedi tane var: runs:read, threads:read, money:read, audit:read, users:read, catalog:read ve payloads:read. *:read hepsini kapsamaya devam ediyor, yani mevcut hiçbir yetki erişim kaybetmedi — bölünme kişi başına tercih ettiğiniz bir şey.

// One person, one organization, two different answers:
{ roles: ['viewer'], permissions: ['*:read'] }                    // sees everything
{ roles: ['viewer'], permissions: ['runs:read', 'catalog:read'] } // sees runs, not conversations

// The seven read groups:
//   runs:read      runs, traces, steps, approvals, metrics
//   threads:read   thread messages, working memory, injected context
//   money:read     usage, cost, the price table, organization budgets
//   audit:read     who did what, and when
//   users:read     the organization's user list
//   catalog:read   agents, tools, workflows, policy, providers — no customer data
//   payloads:read  event bodies, trigger inputs, knowledge text, handler error text

['runs:read', 'catalog:read'] taşıyan Ayşe bir koşunun başarısız olduğunu görür; müşterinin oraya ne yazdığını da, hangi olay gövdesinin patladığını da, bir ajanın aradığı bilgi metnini de açamaz.

catalog:read ajanları, araçları, iş akışlarını, politikayı, sağlayıcıları ve operasyon listelerini gösterir. payloads:read ise onların arkasındaki veri için ayrı bir yetkidir: karantinaya alınmış bir olayın payload'ı, bir işleyicinin ondan ürettiği hata metni, zamanlanmış bir tetikleyicinin input ve lastError alanları, ve POST /knowledge/search'ün döndürdüğü metin. Hata metninin gövdeyle aynı yetkide olması bilinçli — işleyici payload'ın üzerinde çalışır, yani veri hakkında söyledikleri de veridir.

// GET /dead-events        — listed, contents withheld
[{ "id": "e1", "topic": "orders.created", "consumer": "billing",
   "status": "quarantined", "attempts": 8,
   "payloadRestricted": true, "errorRestricted": true }]

// GET /scheduler/triggers — 'input' dropped, 'lastError' replaced
[{ "name": "nightly-report", "lastRun": 1731..., "lastErrorRestricted": true }]

// POST /knowledge/search  — refused: the whole response IS the corpus
403

Yalnızca catalog:read taşıyan bir çağıran karantinadaki olayları yine listeler, hangi tetikleyicinin başarısız olduğunu yine görür. İçerik yerine payloadRestricted: true ve errorRestricted: true alır; /knowledge/search ise doğrudan reddedilir — orada cevabın tamamı korpustur, verilecek daha dar bir cevap yoktur.