vaspera-guard

@vaspera/guard

TypeScript SDK for VasperaGuard - AI Agent Safety & Governance.

Installation

npm install @vaspera/guard
# or
yarn add @vaspera/guard
# or
pnpm add @vaspera/guard

Quick Start

import { Guard } from '@vaspera/guard';

const guard = new Guard({ apiKey: 'vg_...' });

// Check if a command is safe
const result = await guard.check('rm -rf ./temp');

if (result.allowed) {
  console.log('Command is safe to execute');
} else if (result.requiresApproval) {
  console.log('Command requires human approval');
  // Request approval via Slack
  const approval = await guard.requestApproval(result.checkId, {
    channel: 'slack',
    slackChannel: '#devops-approvals'
  });
} else {
  console.log('Command blocked:', result.reason);
  console.log('Suggestions:', result.suggestions);
}

Features

• Command Safety Analysis - Check commands before execution
• Human-in-the-Loop Approval - Request approval via Slack, email, or webhook
• Policy Management - Create and manage safety policies
• Audit Trail - Query audit logs for compliance
• TypeScript First - Full type definitions included

API Reference

Constructor

const guard = new Guard({
  apiKey: 'vg_...',           // Required: Your API key
  baseUrl: 'https://...',     // Optional: Custom API URL
  timeout: 30000,             // Optional: Request timeout (ms)
  environment: 'production',  // Optional: Default environment
  project: 'my-app',          // Optional: Default project
  policies: ['policy-1']      // Optional: Default policies
});

Check Command

const result = await guard.check('npm run build', {
  agentId: 'my-agent',
  context: {
    environment: 'production',
    project: 'backend-api'
  }
});

// Result shape
{
  allowed: boolean;
  blocked: boolean;
  requiresApproval: boolean;
  riskScore: number;        // 0-1
  riskLevel: 'low' | 'medium' | 'high' | 'critical';
  reason: string;
  suggestions: string[];
  patterns: string[];       // Dangerous patterns detected
  nearMisses: NearMiss[];   // Typo detection
  checkId: string;
  timestamp: string;
}

Check and Execute

import { execSync } from 'child_process';

// Throws if blocked or requires approval
const { result, check } = await guard.checkAndExecute(
  'ls -la',
  async (cmd) => execSync(cmd).toString()
);

Request Approval

// Slack
const approval = await guard.requestApproval(checkId, {
  channel: 'slack',
  slackChannel: '#devops',
  timeoutMinutes: 30
});

// Email
const approval = await guard.requestApproval(checkId, {
  channel: 'email',
  emails: ['[e-mail]'],
  timeoutMinutes: 60
});

// Webhook
const approval = await guard.requestApproval(checkId, {
  channel: 'webhook',
  webhookUrl: 'https://your-app.com/webhooks/approval',
  webhookHeaders: { 'X-Custom-Header': 'value' }
});

Wait for Approval

const approval = await guard.waitForApproval(approvalId, {
  timeoutMs: 300000,      // 5 minutes
  pollIntervalMs: 5000    // Poll every 5 seconds
});

if (approval.status === 'approved') {
  // Execute command
}

Policy Management

// Create policy
const policy = await guard.createPolicy({
  name: 'production-safety',
  rules: [
    { pattern: 'DROP TABLE', action: 'block' },
    { pattern: 'rm -rf /', action: 'block' },
    { pattern: 'chmod 777', action: 'require_approval' }
  ]
});

// Get all policies
const policies = await guard.getPolicies();

// Get specific policy
const policy = await guard.getPolicy('policy-id');

// Delete policy
await guard.deletePolicy('policy-id');

Audit Log

const audit = await guard.getAuditLog({
  limit: 100,
  riskLevel: 'critical',
  agentId: 'my-agent',
  startDate: '2024-01-01T00:00:00Z'
});

for (const entry of audit.entries) {
  console.log(entry.command, entry.riskLevel, entry.checkResult);
}

Error Handling

import {
  Guard,
  GuardError,
  AuthenticationError,
  RateLimitError
} from '@vaspera/guard';

try {
  await guard.check('some command');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof GuardError) {
    console.log('API error:', error.code, error.message);
  }
}

License

MIT