guardrail-core 1.0.0

package/src/types.ts

@@ -0,0 +1,441 @@
+// ==========================================
+// PERMISSION TYPES
+// ==========================================
+
+export interface FilesystemPermissions {
+  allowedPaths: string[];
+  deniedPaths: string[];
+  operations: ('read' | 'write' | 'delete' | 'execute')[];
+  maxFileSize: number; // in bytes
+  [key: string]: unknown;
+}
+
+export interface NetworkPermissions {
+  allowedDomains: string[];
+  deniedDomains: string[];
+  maxRequests: number; // per minute
+  allowedProtocols: ('http' | 'https' | 'ws' | 'wss')[];
+  [key: string]: unknown;
+}
+
+export interface ShellPermissions {
+  allowedCommands: string[];
+  deniedCommands: string[];
+  requireConfirmation: string[]; // commands that need user approval
+  allowEnvironmentVariables: boolean;
+  [key: string]: unknown;
+}
+
+export interface ResourceLimits {
+  maxMemoryMB: number;
+  maxCpuPercent: number;
+  maxTokens: number;
+  maxExecutionTimeMs: number;
+  [key: string]: unknown;
+}
+
+export interface AgentPermissionScope {
+  filesystem: FilesystemPermissions;
+  network: NetworkPermissions;
+  shell: ShellPermissions;
+  resources: ResourceLimits;
+}
+
+// ==========================================
+// ACTION TYPES
+// ==========================================
+
+export interface FilesystemDetails {
+  operation: 'read' | 'write' | 'delete' | 'execute';
+  path: string;
+  content?: string;
+  size?: number;
+}
+
+export interface NetworkDetails {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+export interface ShellDetails {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export type ActionDetails = FilesystemDetails | NetworkDetails | ShellDetails;
+
+export interface ActionAttempt {
+  agentId: string;
+  taskId: string;
+  actionType: string;
+  category: 'code' | 'file' | 'network' | 'shell';
+  details: ActionDetails;
+  reasoning?: string;
+}
+
+export interface ActionDecision {
+  allowed: boolean;
+  reason: string;
+  alternativeSuggestion?: string;
+  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  requiresApproval: boolean;
+}
+
+// ==========================================
+// EVALUATION TYPES
+// ==========================================
+
+export interface Evaluation {
+  passed: boolean;
+  reason: string;
+  violatedRules: string[];
+  suggestions: string[];
+}
+
+export interface SimpleValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// ==========================================
+// CHECKPOINT TYPES
+// ==========================================
+
+export interface FileSnapshot {
+  path: string;
+  originalContent: string;
+  originalHash: string;
+  [key: string]: unknown;
+}
+
+export interface Checkpoint {
+  id: string;
+  agentId: string;
+  taskId: string;
+  modifiedFiles: FileSnapshot[];
+  resourcesUsed: ResourceUsage;
+  createdAt: Date;
+}
+
+export interface ResourceUsage {
+  memoryMB: number;
+  cpuPercent: number;
+  tokensUsed: number;
+  executionTimeMs: number;
+  apiCalls: number;
+  [key: string]: unknown;
+}
+
+export interface LimitCheck {
+  withinLimits: boolean;
+  violations: string[];
+  current: ResourceUsage;
+  limits: ResourceLimits;
+}
+
+export interface RollbackResult {
+  success: boolean;
+  filesRestored: number;
+  errors: string[];
+}
+
+// ==========================================
+// INJECTION DETECTION TYPES
+// ==========================================
+
+export interface InjectionScanRequest {
+  content: string;
+  contentType: 'user_input' | 'code' | 'data_source';
+  context?: {
+    source: string;
+    metadata?: Record<string, unknown>;
+  };
+}
+
+export interface Detection {
+  type: string;
+  pattern: string;
+  location: {
+    start: number;
+    end: number;
+    line?: number;
+  };
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  confidence: number;
+  description: string;
+}
+
+export interface InjectionScanResult {
+  verdict: 'CLEAN' | 'SUSPICIOUS' | 'MALICIOUS' | 'BLOCKED';
+  confidence: number;
+  detections: Detection[];
+  sanitizedContent?: string;
+  recommendation: {
+    action: 'allow' | 'sanitize' | 'block' | 'review';
+    reason: string;
+  };
+  scanDuration: number;
+}
+
+export interface ProcessedInput {
+  original: string;
+  processed: string;
+  wasSanitized: boolean;
+  detections: Detection[];
+}
+
+// ==========================================
+// OUTPUT VALIDATION TYPES
+// ==========================================
+
+export interface CodeOutput {
+  code: string;
+  language: string;
+  outputType: 'code' | 'config' | 'documentation';
+  metadata?: Record<string, unknown>;
+}
+
+export interface Context {
+  projectPath?: string;
+  existingFiles?: string[];
+  dependencies?: Record<string, string>;
+  framework?: string;
+}
+
+export interface StageResult {
+  stageName: string;
+  passed: boolean;
+  score: number;
+  issues: ValidationIssue[];
+  warnings: string[];
+  duration: number;
+}
+
+export interface ValidationIssue {
+  type: string;
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+  location?: {
+    line: number;
+    column: number;
+  };
+  suggestion?: string;
+}
+
+export interface ValidationRequest {
+  output: CodeOutput;
+  context?: Context;
+  request?: string; // original user request
+}
+
+export interface DetailedValidationResult {
+  verdict: 'ACCEPT' | 'MODIFY' | 'REJECT' | 'HUMAN_REVIEW';
+  confidence: number;
+  stages: StageResult[];
+  overallScore: number;
+  modifiedOutput?: string;
+  recommendation: string;
+}
+
+// ==========================================
+// HALLUCINATION DETECTION TYPES
+// ==========================================
+
+export interface PackageCheck {
+  exists: boolean;
+  name: string;
+  version?: string;
+  registry: string;
+  alternativeSuggestions?: string[];
+}
+
+export interface APICheck {
+  exists: boolean;
+  package: string;
+  method: string;
+  signature?: string;
+  documentation?: string;
+  alternativeSuggestions?: string[];
+}
+
+export interface CodeIntent {
+  primary: string;
+  secondary: string[];
+  entities: string[]; // packages, functions, variables involved
+  operations: string[]; // what the code does
+}
+
+export interface RequestIntent {
+  goal: string;
+  constraints: string[];
+  expectedEntities: string[];
+  expectedOperations: string[];
+}
+
+export interface IntentComparison {
+  alignmentScore: number;
+  matches: string[];
+  mismatches: string[];
+  recommendation: string;
+}
+
+// ==========================================
+// AUDIT TYPES
+// ==========================================
+
+export interface AuditEvent {
+  agentId: string;
+  taskId: string;
+  correlationId: string;
+  sequenceNumber: number;
+  actionType: string;
+  category: string;
+  input?: unknown;
+  output?: unknown;
+  target?: {
+    type: string;
+    path?: string;
+    url?: string;
+  };
+  reasoning: {
+    summary: string;
+    considerations: string[];
+    confidence: number;
+  };
+  status: 'SUCCESS' | 'FAILURE' | 'BLOCKED' | 'PENDING_APPROVAL' | 'ROLLED_BACK';
+  error?: {
+    message: string;
+    code: string;
+    stack?: string;
+  };
+  impact?: {
+    filesModified?: string[];
+    linesAdded?: number;
+    linesDeleted?: number;
+  };
+  diff?: {
+    before: string;
+    after: string;
+    unified: string;
+  };
+  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  riskFactors: string[];
+  sensitiveData: boolean;
+  piiInvolved: boolean;
+  duration?: number;
+  timestamp: Date;
+  previousHash?: string;
+}
+
+export interface Diff {
+  before: string;
+  after: string;
+  unified: string;
+}
+
+export interface CodeGenParams {
+  taskId: string;
+  agentId: string;
+  prompt: string;
+  generatedCode: string;
+  language: string;
+  reasoning: string;
+}
+
+export interface CodeModParams {
+  taskId: string;
+  agentId: string;
+  filePath: string;
+  originalCode: string;
+  modifiedCode: string;
+  reasoning: string;
+}
+
+export interface ShellParams {
+  taskId: string;
+  agentId: string;
+  command: string;
+  args: string[];
+  output: string;
+  exitCode: number;
+}
+
+export interface AuditQuery {
+  agentId?: string;
+  taskId?: string;
+  correlationId?: string;
+  startDate?: Date;
+  endDate?: Date;
+  actionType?: string;
+  status?: string;
+  riskLevel?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface QueryResult {
+  events: AuditEvent[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export interface Timeline {
+  taskId: string;
+  events: AuditEvent[];
+  summary: {
+    totalActions: number;
+    successfulActions: number;
+    failedActions: number;
+    blockedActions: number;
+    duration: number;
+  };
+}
+
+export interface Changes {
+  filePath: string;
+  timestamp: Date;
+  diff: Diff;
+  agent: string;
+  reasoning: string;
+}
+
+export interface Attribution {
+  projectId: string;
+  period: DateRange;
+  aiGenerated: {
+    lines: number;
+    files: number;
+    percentage: number;
+  };
+  humanWritten: {
+    lines: number;
+    files: number;
+    percentage: number;
+  };
+  breakdown: {
+    agent: string;
+    lines: number;
+    files: number;
+  }[];
+}
+
+export interface DateRange {
+  start: Date;
+  end: Date;
+}
+
+export type ReportType = 'audit' | 'compliance' | 'security' | 'attribution';
+
+export interface Report {
+  type: ReportType;
+  period: DateRange;
+  summary: Record<string, unknown>;
+  details: unknown[];
+  generatedAt: Date;
+}

package/src/utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generate a unique correlation ID for tracking related actions
+ */
+export declare function generateCorrelationId(): string;
+/**
+ * Generate a task ID
+ */
+export declare function generateTaskId(): string;
+/**
+ * Calculate SHA-256 hash of content
+ */
+export declare function calculateHash(content: string): string;
+/**
+ * Calculate content entropy (randomness measure for secret detection)
+ */
+export declare function calculateEntropy(str: string): number;
+/**
+ * Mask sensitive value for logging
+ */
+export declare function maskSensitiveValue(value: string): string;
+/**
+ * Check if a path is within allowed paths
+ */
+export declare function isPathAllowed(path: string, allowedPaths: string[], deniedPaths: string[]): boolean;
+/**
+ * Check if a domain is allowed
+ */
+export declare function isDomainAllowed(url: string, allowedDomains: string[], deniedDomains: string[]): boolean;
+/**
+ * Sanitize error message for safe logging
+ */
+export declare function sanitizeError(error: unknown): {
+    message: string;
+    code?: string;
+};
+//# sourceMappingURL=utils.d.ts.map

package/src/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqBpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EAAE,EACtB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAuBT;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,EAAE,EACxB,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CA4BT;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAQhF"}

package/src/utils.ts

@@ -0,0 +1,140 @@
+import crypto from 'crypto';
+
+/**
+ * Generate a unique correlation ID for tracking related actions
+ */
+export function generateCorrelationId(): string {
+  return `corr_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
+}
+
+/**
+ * Generate a task ID
+ */
+export function generateTaskId(): string {
+  return `task_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
+}
+
+/**
+ * Calculate SHA-256 hash of content
+ */
+export function calculateHash(content: string): string {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Calculate content entropy (randomness measure for secret detection)
+ */
+export function calculateEntropy(str: string): number {
+  const len = str.length;
+  const frequencies: Record<string, number> = {};
+
+  for (let i = 0; i < len; i++) {
+    const char = str[i];
+    if (char) {
+      frequencies[char] = (frequencies[char] || 0) + 1;
+    }
+  }
+
+  let entropy = 0;
+  for (const char in frequencies) {
+    const frequency = frequencies[char];
+    if (frequency !== undefined) {
+      const p = frequency / len;
+      entropy -= p * Math.log2(p);
+    }
+  }
+
+  return entropy;
+}
+
+/**
+ * Mask sensitive value for logging
+ */
+export function maskSensitiveValue(value: string): string {
+  if (value.length <= 8) {
+    return '***';
+  }
+  return `${value.substring(0, 4)}...${value.substring(value.length - 4)}`;
+}
+
+/**
+ * Check if a path is within allowed paths
+ */
+export function isPathAllowed(
+  path: string,
+  allowedPaths: string[],
+  deniedPaths: string[]
+): boolean {
+  const normalizedPath = path.replace(/\\/g, '/');
+
+  // Check denied paths first (more restrictive)
+  for (const deniedPath of deniedPaths) {
+    if (normalizedPath.startsWith(deniedPath.replace(/\\/g, '/'))) {
+      return false;
+    }
+  }
+
+  // If no allowed paths specified, allow all (except denied)
+  if (allowedPaths.length === 0) {
+    return true;
+  }
+
+  // Check allowed paths
+  for (const allowedPath of allowedPaths) {
+    if (normalizedPath.startsWith(allowedPath.replace(/\\/g, '/'))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if a domain is allowed
+ */
+export function isDomainAllowed(
+  url: string,
+  allowedDomains: string[],
+  deniedDomains: string[]
+): boolean {
+  try {
+    const urlObj = new URL(url);
+    const hostname = urlObj.hostname;
+
+    // Check denied domains first
+    for (const deniedDomain of deniedDomains) {
+      if (hostname === deniedDomain || hostname.endsWith(`.${deniedDomain}`)) {
+        return false;
+      }
+    }
+
+    // If no allowed domains specified, allow all (except denied)
+    if (allowedDomains.length === 0) {
+      return true;
+    }
+
+    // Check allowed domains
+    for (const allowedDomain of allowedDomains) {
+      if (hostname === allowedDomain || hostname.endsWith(`.${allowedDomain}`)) {
+        return true;
+      }
+    }
+
+    return false;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Sanitize error message for safe logging
+ */
+export function sanitizeError(error: unknown): { message: string; code?: string } {
+  if (error instanceof Error) {
+    return {
+      message: error.message.replace(/\/[^\s:]+/g, '[path]'),
+      code: (error as any).code,
+    };
+  }
+  return { message: 'Unknown error occurred' };
+}