Denetim kaydı (audit)

Uyumluluk (SOC2/ISO benzeri) veya sadece "kim ne zaman ne yaptı" sorusuna güvenilir cevap gerektiğinde iki ayrı denetim katmanı devreye girer. Birincisi @gnldev/auth-ee'nin AuditSink'i: her authorize çağrısının allow/deny kararını (kim, hangi path/method, hangi organizasyon) yazar — createEnterpriseAuth içine gömülüdür, elle çağırmanız gerekmez. İkincisi Studio'nun kendi yönetim-eylemi günlüğüdür: organizasyon/kullanıcı oluşturma-silme, policy güncelleme, run purge, agent promote gibi YAZMA eylemlerini GET /audit ile geriye okunabilir tutar.

Kritik garanti: aktör alanı istemcinin iddia ettiği bir şey değil, doğrulanmış kimlikten (Principal.id) türetilir — paylaşımlı bir token arkasında birden çok kişi çalışıyorsa x-gnl-actor header'ı ile kişi bazlı iz bırakılabilir, ama hiçbir istemci başka birinin kimliğini taklit edip kayda "ben yaptım değil" diyemez.

import { createEnterpriseAuth, createJournalAuditSink, consoleAuditSink } from '@gnldev/auth-ee';
import type { AuditSink, AuditEvent } from '@gnldev/auth-ee';
import { toJournal } from '@gnldev/durable';

@gnldev/auth-ee paralı/lisanslı bir pakettir — geçerli bir lisans anahtarı olmadan createEnterpriseAuth fallback'e düşer ve verilen audit sink'i devreye girmez. Journal-destekli kalıcı sink için storage'ın run journal'ı toJournal (@gnldev/durable) ile sarılır.

1. Kalıcı audit istiyorsanız createJournalAuditSink ile bir sink oluşturup createEnterpriseAuth'a audit seçeneği olarak verin — verilmezse varsayılan uçucu consoleAuditSink kullanılır (yalnız konsola yazar, kalıcı değildir):

const auth = createEnterpriseAuth({
  licenseKey,
  userStore,
  audit: createJournalAuditSink(toJournal(storage.runs)), // durable: decisions are written to the journal
  fallback,
});

Her authorize(principal, ctx) çağrısı artık otomatik olarak recordDecision üzerinden sink'e bir AuditEvent yazar — ayrıca kod yazmanız gerekmez.

2. Yazılan kararları geriye okumak için readJournalAudit kullanılır (en yeni önce döner):

import { readJournalAudit } from '@gnldev/auth-ee';

const events = await readJournalAudit(toJournal(storage.runs));
// [{ ts, principalId, orgId, path, method, action, allowed, reason }, ...]

3. Bu, Studio'nun kendi yönetim-eylemi günlüğünden AYRIDIR. Studio, her başarılı YAZMA eylemini (ör. org.create, policy.update, run.purge, agent.promote) kendi __audit__ log'una düşürür ve organizasyon kapsamlı, filtrelenebilir bir uçtan sunar:

GET /audit?limit=200&action=policy.update&q=acme
// -> { items: [{ id, at, actor, action, target, org?, detail? }, ...] } (newest first)

Kimliğe bağlı (org'lu) bir principal yalnız kendi organizasyonunun kayıtlarını görür (?org= yok sayılır); bağsız (operatör) kimlik ?org= ile isteğe bağlı süzebilir.