JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 29
  • Score
    100M100P100Q73565F
  • License Apache-2.0

AI agent runtime security: context-preserving tokenization, risk scoring, and policy enforcement

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/core

Node.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ır

Hafta 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 + trim
  • PHONE, 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 denenebilir PriventAPIError

Geliştirme

# Kurulum
pnpm install

# Build (ESM + CJS + .d.ts)
pnpm build

# Testler (48 test)
pnpm test

# TypeScript tip kontrolü
pnpm typecheck

Benchmarklar (B1-B5)

# Geçerli benchmark raporunu üret
pnpm bench

# Baseline dosyasını güncelle (intentional only)
pnpm bench:update-baseline

Raporlar 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.json

Lisans

Apache-2.0