vexis-core

Open-source trust scoring and anomaly detection for AI agents. Zero dependencies. MIT licensed.

This is the core algorithm library extracted from Vexis — cryptographic identity and trust infrastructure for AI agents. Use it to compute trust scores, run EigenTrust graph algorithms, apply temporal decay, and detect behavioral anomalies in your own systems.

Install

npm install vexis-core

What's Included

| Module | Functions | Description | |--------|-----------|-------------| | Trust Score | computeTrustScore | 3-factor weighted formula (success rate, maturity, recent failure rate) with asymmetric penalties | | EigenTrust | buildLocalTrustMatrix, eigenTrustIterate, scaleToScoreRange, blendScores | Stanford EigenTrust algorithm for transitive trust propagation across graphs | | Trust Decay | applyTrustDecay | Exponential decay toward neutral for inactive agents | | Anomaly Detection | detectScopeEscalation, detectFirstContact, detectBaselineDeviation, detectNewAction | Rule-based and statistical anomaly detectors |

Usage

Trust Score Computation

import { computeTrustScore } from 'vexis-core';

const result = computeTrustScore({
  verificationSuccessCount: 95,
  verificationFailureCount: 5,
  selfAttestationSuccessCount: 40,
  selfAttestationFailureCount: 2,
  thirdPartyAttestationSuccessCount: 20,
  thirdPartyAttestationFailureCount: 1,
  totalInteractions: 163,
  ageDays: 45,
  recentFailures: 1,
  recentTotal: 30,
  nonRoutineRevocations: 0,
});

console.log(result.score);   // 0-100
console.log(result.factors);  // { successRate, maturity, recentFailureRate }

EigenTrust (Graph-Based Trust)

import {
  buildLocalTrustMatrix,
  eigenTrustIterate,
  scaleToScoreRange,
  blendScores,
} from 'vexis-core';

// Build trust matrix from edge weights
const edges = [
  { sourceId: 'agent-a', targetId: 'system-1', weights: { totalInteractions: 50, successCount: 48 } },
  { sourceId: 'agent-b', targetId: 'system-1', weights: { totalInteractions: 30, successCount: 15 } },
];

const { matrix, nodeIds } = buildLocalTrustMatrix(edges);
const eigenScores = eigenTrustIterate(matrix, nodeIds);
const scaled = scaleToScoreRange(eigenScores);

// Blend EigenTrust with local score (60/40 default)
const finalScore = blendScores(scaled['agent-a'], localScore);

Trust Decay

import { applyTrustDecay } from 'vexis-core';

// Agent inactive for 30 days, original score 85
const decayed = applyTrustDecay(85, 30);
// Returns ~77 (decays toward floor of 50)

// Custom decay rate (faster decay)
const aggressive = applyTrustDecay(85, 30, 0.05);

Anomaly Detection

import {
  detectScopeEscalation,
  detectFirstContact,
  detectBaselineDeviation,
  detectNewAction,
} from 'vexis-core';

// Scope escalation: action not in capabilities
const signal = detectScopeEscalation('admin:delete', [
  { name: 'data:read', scope: 'default' },
]);
// Returns { type: 'scope_escalation', severity: 'high', detail: '...' }

// First contact: agent interacting with new system
const contact = detectFirstContact(false, 'api.stripe.com');
// Returns { type: 'first_contact', severity: 'low', detail: '...' }

// Baseline deviation: z-score anomaly detection
const baseline = detectBaselineDeviation(
  150,  // current value
  { mean: 50, stddev: 20, sampleCount: 100 },
  'Hourly request volume'
);
// Returns { type: 'baseline_anomaly', severity: 'medium', detail: '...' }

// New action: never-before-seen action
const newAction = detectNewAction(
  'billing:refund',
  { 'data:read': 500, 'data:write': 200 },
  700
);
// Returns { type: 'baseline_anomaly', severity: 'medium', detail: '...' }

Trust Score Formula

The score is a weighted sum of 3 factors, scaled to 0-100:

baseScore = (successRate × 0.50 + maturity × 0.25 + (1 - recentFailureRate) × 0.25) × 100

Success rate combines verification and attestation outcomes (third-party attestations weighted 2x).

Maturity requires both volume and time: min(1, interactions/100) × min(1, ageDays/30).

Asymmetric penalties pull scores down faster than successes push them up:

• Recent failure penalty: if >5 failures in 24h, deduct up to 20 points
• Revocation penalty: 5 points per non-routine revocation, max 25

New agents start at 50 (neutral).

EigenTrust Algorithm

Implementation of the EigenTrust algorithm (Kamvar et al., Stanford) for computing global trust from local trust relationships.

• Power iteration with configurable damping factor (default α=0.15)
• Convergence detection via L1 norm (ε=1e-6)
• Sybil-resistant via pre-trusted seed distribution
• Score blending: 60% EigenTrust + 40% local formula (configurable)

Types

interface TrustFactors {
  successRate: number;       // 0-1
  maturity: number;          // 0-1
  recentFailureRate: number; // 0-1
}

interface RiskSignal {
  type: 'scope_escalation' | 'velocity_spike' | 'unusual_timing' | 'first_contact' | 'baseline_anomaly';
  severity: 'low' | 'medium' | 'high';
  detail: string;
}

interface Capability {
  name: string;  // "namespace:action" format
  scope: string;
}

License

MIT