Package Exports
- @priventai/core
- @priventai/core/contracts
- @priventai/core/package.json
- @priventai/core/vault/memory
Readme
@priventai/core
AI agent iş akışları için güvenlik çalışma zamanı. Hassas verileri LLM'lere ulaşmadan önce [EMAIL_001] gibi oturum kapsamlı yer tutuculara dönüştürür; güvenilen çıkış noktalarında ise orijinal değerleri geri yükler.
Kurulum
npm install @priventai/core
# veya
pnpm add @priventai/coreNode.js 20 veya üzeri gereklidir.
Hızlı Başlangıç
import { PriventClient } from '@priventai/core';
const client = new PriventClient({
apiKey: process.env.PRIVENT_API_KEY, // opsiyonel; olmadan regex-only mod
});
await client.withSession(async ({ vault, traceId }) => {
// 1. Girişi tokenize et — LLM ham veriyi görmez
const { tokenizedText, entities } = await client.tokenizer.tokenize(
'Müşteri: ali@sirket.com, Kart: 4111111111111111',
vault,
{ kinds: ['EMAIL', 'CREDIT_CARD'] },
);
// tokenizedText === "Müşteri: [EMAIL_001], Kart: [CREDIT_CARD_001]"
// 2. Agent/LLM ile çalış
const agentOutput = await myLLM.invoke(tokenizedText);
// 3. Güvenilen çıkışta detokenize et
const restored = await client.tokenizer.detokenize(agentOutput, vault);
// Orijinal değerler geri yüklendi
return restored;
}); // vault.destroy() otomatik çağrılırHafta 1 Kapsamı — Ne Var, Ne Yok
Bu sürüm (Hafta 1 — Monorepo Temeli + @priventai/core) aşağıdakileri içerir:
| Bileşen | Durum | Açıklama |
|---|---|---|
PriventClient |
✅ | withSession<T>(), bağımlılık enjeksiyonu |
InMemoryTokenVault |
✅ | Map tabanlı, TTL desteği, 10k giriş limiti |
HybridTokenizer |
✅ | Regex geçişi (EMAIL, PHONE, CREDIT_CARD, IBAN, SSN, API_KEY, JWT, AWS_KEY, IP, URL) |
detokenizeDeep |
✅ | Derin nesne/dizi yürüyüşü, döngü güvenli |
PriventError hiyerarşisi |
✅ | 9 alt sınıf, retryable bayrağı, toJSON() scrubbing |
HttpClient |
✅ | Fetch tabanlı, üstel geri çekilme + jitter, idempotency anahtarları |
NoopRiskScorer |
⚙️ | Hafta 1 taslağı; CloudRiskScorer Hafta 3'te eklenir |
NoopAuditLogger |
⚙️ | Hafta 1 taslağı; CloudAuditLogger Hafta 3'te eklenir |
NoopPolicyEngine |
⚙️ | Hafta 1 taslağı; YAML kural motoru Hafta 3'te eklenir |
| ML entity çıkarımı | ⚙️ | ml-entity-extractor.ts foundation; aktif backend Hafta 3'te |
| n8n node'ları | ⏳ | Hafta 2 |
| LangGraph adapter | ⏳ | Hafta 5-6 |
| CrewAI adapter | ⏳ | Hafta 7+ |
API Referansı
PriventClient
Ana giriş noktası. Tüm bileşenleri bir arada tutar.
const client = new PriventClient({
apiKey?: string; // PRIVENT_API_KEY env'den okunur
baseUrl?: string; // varsayılan: https://api.privent.ai
vaultFactory?: VaultFactory; // varsayılan: InMemoryVaultFactory
tokenizer?: Tokenizer; // varsayılan: HybridTokenizer (regex-only)
riskScorer?: RiskScorer; // varsayılan: NoopRiskScorer
policyEngine?: PolicyEngine; // varsayılan: NoopPolicyEngine
auditLogger?: AuditLogger; // varsayılan: NoopAuditLogger
maxRetries?: number; // varsayılan: 2
timeout?: number; // varsayılan: 30_000 ms
failPolicy?: 'open' | 'closed'; // varsayılan: 'open'
});client.withSession<T>(fn)
Oturum vault'u açar, fn'yi çalıştırır, finally bloğunda vault'u yok eder.
const result = await client.withSession(async ({ vault, sessionId, traceId }) => {
// vault: TokenVault — tokenize/detokenize için
// sessionId: string — bu oturuma özgü UUID
// traceId: string — tüm işlemler için korelasyon ID'si
return 'done';
});TokenVault / InMemoryTokenVault
Oturum kapsamlı, çift yönlü token deposu.
import { InMemoryTokenVault } from '@priventai/core/vault/memory';
const vault = new InMemoryTokenVault('session-1');
// Token kaydet
await vault.store({ token: '[EMAIL_001]', value: 'ali@test.com', kind: 'EMAIL', ... });
// Token ile bul
const entry = await vault.retrieve('[EMAIL_001]');
// Değer ile bul (determinizm)
const entry = await vault.findByValue('ali@test.com', 'EMAIL');
// Sayaç al (tokenizer tarafından kullanılır)
const counter = await vault.nextCounter('EMAIL'); // 1, 2, 3, ...
// Vault'u yok et (session sonunda)
await vault.destroy();Normalizasyon kuralları (determinizm için):
EMAIL→ küçük harf + trimPHONE,CREDIT_CARD,IBAN→ yalnızca rakamlar- Diğerleri → trim
HybridTokenizer
Regex tabanlı entity tespiti ve token değişimi.
const { tokenizedText, entities } = await client.tokenizer.tokenize(text, vault, {
kinds: ['EMAIL', 'PHONE'], // hangi entity'leri tespit et
entityHints: ['customer_email'], // Hafta 3'te ML'e ipucu verir
entityExtractionMode: 'regex', // 'regex' | 'ml' | 'auto'
allowList: ['noreply@sistem.com'],// asla tokenize etme
denyList: ['gizli-proje'], // her zaman tokenize et
customPatterns: [{ // özel regex'ler
kind: 'PROJECT_CODE',
regex: /PROJ-\d{4}/g,
confidence: 0.95,
}],
});Token formatı: [KIND_NNN] — örn. [EMAIL_001], [CREDIT_CARD_003]
Determinizm: Aynı oturum içinde aynı değer → aynı token. Farklı oturumlar → farklı token'lar (korelasyon saldırısı önlemi).
Desteklenen entity'ler:
| Kind | Örnekler | Güven |
|---|---|---|
EMAIL |
ali@sirket.com |
0.95 |
PHONE |
+90 532 123 45 67, (212) 555-1234 |
0.80 |
CREDIT_CARD |
4111 1111 1111 1111 (Luhn kontrolü) |
0.98 |
IBAN |
TR33 0006 1005 1978 6457 8413 26 |
0.97 |
SSN |
123-45-6789 |
0.90 |
API_KEY |
sk-abc123..., ghp_..., xoxb-... |
0.88 |
JWT |
eyJhbGci... |
0.98 |
AWS_KEY |
AKIA... |
0.99 |
IP_ADDRESS |
192.168.1.1 |
0.85 |
URL |
https://... |
0.90 |
detokenizeDeep
Token içerebilecek herhangi bir değeri (string, nesne, dizi) tarar ve bulduğu token'ları orijinal değerlerle değiştirir.
import { detokenizeDeep } from '@priventai/core';
const original = await detokenizeDeep(
{ email: '[EMAIL_001]', data: ['[PHONE_001]', 'plain text'] },
vault,
);
// { email: 'ali@test.com', data: ['05321234567', 'plain text'] }- Döngü güvenli (WeakSet)
- Derinlik limiti: 64
- Binary verileri (ArrayBuffer) atlar
indexOf('[')hızlı-yol optimizasyonu
Hata Hiyerarşisi
import {
PriventError, // temel sınıf
PriventConfigError, // yapılandırma hatası
PriventAuthError, // 401/403
PriventRateLimitError, // 429
PriventAPIError, // 4xx/5xx
PriventNetworkError, // ağ hatası
PriventTimeoutError, // zaman aşımı
PriventValidationError, // girdi doğrulama hatası
PriventVaultFullError, // vault 10k limitini aştı
PriventVaultDestroyedError, // destroy sonrası erişim
} from '@priventai/core';
try {
await client.tokenizer.tokenize(text, vault);
} catch (err) {
if (err instanceof PriventError) {
console.log(err.code); // makine tarafından okunabilir
console.log(err.retryable); // yeniden dene?
console.log(err.toJSON()); // hassas alan temizleme ile JSON
}
}HttpClient
Privent Cloud ile iletişim için düşük seviyeli HTTP istemcisi. Normalde doğrudan kullanılmaz — PriventClient tarafından dahili olarak yönetilir.
- Yeniden deneme: Üstel geri çekilme + ±%20 jitter, maks. 10s
- Idempotency: Her istek için UUID anahtar, yeniden denemeler aynı anahtarı kullanır
- Zaman aşımı: AbortController tabanlı, varsayılan 30s
- Hata eşlemesi: 401 →
PriventAuthError, 429 →PriventRateLimitError, 5xx → yeniden denenebilirPriventAPIError
Geliştirme
# Kurulum
pnpm install
# Build (ESM + CJS + .d.ts)
pnpm build
# Testler (48 test)
pnpm test
# TypeScript tip kontrolü
pnpm typecheckBenchmarklar (B1-B5)
# Geçerli benchmark raporunu üret
pnpm bench
# Baseline dosyasını güncelle (intentional only)
pnpm bench:update-baselineRaporlar packages/core/src/__benchmarks__/results/ altına yazılır.
Regresyon kontrolü için root seviyede:
node scripts/bench-compare.mjs \
--current=packages/core/src/__benchmarks__/results/current.json \
--baseline=packages/core/src/__benchmarks__/results/baseline.jsonLisans
Apache-2.0