palaryn 0.1.0 → 0.3.2

package/src/tracing/index.ts

@@ -0,0 +1 @@
+export { GatewayTracer, TracingConfig } from './provider';

package/src/tracing/provider.ts

@@ -0,0 +1,100 @@
+import { Tracer, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { BatchSpanProcessor, SimpleSpanProcessor, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+
+export { SpanKind, SpanStatusCode };
+
+export interface TracingConfig {
+  enabled: boolean;
+  /** Service name reported to the collector. Defaults to 'palaryn'. */
+  service_name?: string;
+  /** Service version reported to the collector. Defaults to '0.1.0'. */
+  service_version?: string;
+  /** Deployment environment (e.g. 'production', 'staging'). Defaults to 'development'. */
+  environment?: string;
+  /** OTLP HTTP endpoint for trace export. Defaults to 'http://localhost:4318/v1/traces'. */
+  otlp_endpoint?: string;
+  /** Use SimpleSpanProcessor instead of BatchSpanProcessor. Useful for testing. */
+  use_simple_processor?: boolean;
+}
+
+/**
+ * GatewayTracer wraps the OpenTelemetry SDK and provides a simple interface
+ * for the gateway pipeline to create spans. When tracing is disabled the
+ * class is a no-op — getTracer() returns undefined and all other methods
+ * are safe to call.
+ */
+export class GatewayTracer {
+  private provider?: NodeTracerProvider;
+  private tracer?: Tracer;
+  private config: TracingConfig;
+
+  constructor(config: TracingConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Initialize the TracerProvider and register it globally.
+   * If config.enabled is false this is a no-op.
+   */
+  setup(): void {
+    if (!this.config.enabled) {
+      // No-op mode — getTracer() will return undefined
+      return;
+    }
+
+    const resource = resourceFromAttributes({
+      'service.name': this.config.service_name || 'palaryn',
+      'service.version': this.config.service_version || '0.1.0',
+      'deployment.environment': this.config.environment || 'development',
+    });
+
+    const exporter = new OTLPTraceExporter({
+      url: this.config.otlp_endpoint || 'http://localhost:4318/v1/traces',
+    });
+
+    const processor: SpanProcessor = this.config.use_simple_processor
+      ? new SimpleSpanProcessor(exporter)
+      : new BatchSpanProcessor(exporter);
+
+    this.provider = new NodeTracerProvider({
+      resource,
+      spanProcessors: [processor],
+    });
+
+    this.provider.register();
+
+    this.tracer = this.provider.getTracer(
+      this.config.service_name || 'palaryn',
+      this.config.service_version || '0.1.0',
+    );
+  }
+
+  /**
+   * Return the active Tracer instance, or undefined when tracing is disabled.
+   * Callers should guard with `if (!tracer) ...` or optional chaining.
+   */
+  getTracer(name?: string): Tracer | undefined {
+    if (!this.provider) {
+      return undefined;
+    }
+    if (name) {
+      return this.provider.getTracer(name);
+    }
+    return this.tracer;
+  }
+
+  /**
+   * Flush pending spans and shut down the provider.
+   * Safe to call even when tracing is disabled.
+   */
+  async shutdown(): Promise<void> {
+    if (this.provider) {
+      await this.provider.shutdown();
+      this.provider = undefined;
+      this.tracer = undefined;
+    }
+  }
+}

package/src/trust/calculator.ts

@@ -0,0 +1,141 @@
+import { AnomalyDetector } from '../anomaly/detector';
+import { AuditLogger } from '../audit/logger';
+import { BudgetManager } from '../budget/manager';
+
+export interface TrustScoreWeights {
+  anomaly_weight: number;
+  high_severity_weight: number;
+  dlp_weight: number;
+  dlp_high_weight: number;
+  error_rate_weight: number;
+  escalation_weight: number;
+  budget_velocity_weight: number;
+}
+
+export interface TrustScoreBreakdown {
+  anomalies: { count: number; high_count: number; impact: number };
+  dlp: { detections: number; high_severity: number; impact: number };
+  error_rate: { pct: number; impact: number };
+  escalations: { count: number; impact: number };
+  budget_velocity: { current_rate: number; impact: number };
+}
+
+export interface TrustScoreResult {
+  actor_id: string;
+  score: number;
+  risk_level: 'low' | 'medium' | 'high' | 'critical';
+  breakdown: TrustScoreBreakdown;
+  calculated_at: string;
+}
+
+export const DEFAULT_WEIGHTS: TrustScoreWeights = {
+  anomaly_weight: 2,
+  high_severity_weight: 5,
+  dlp_weight: 3,
+  dlp_high_weight: 10,
+  error_rate_weight: 1,
+  escalation_weight: 15,
+  budget_velocity_weight: 20,
+};
+
+export class TrustScoreCalculator {
+  constructor(
+    private anomalyDetector: AnomalyDetector,
+    private auditLogger: AuditLogger,
+    private budgetManager: BudgetManager,
+    private weights: TrustScoreWeights = DEFAULT_WEIGHTS,
+  ) {}
+
+  calculate(actorId: string): TrustScoreResult {
+    let score = 100;
+
+    // 1. Anomaly component
+    const actorAlerts = this.anomalyDetector.getAlertsForEntity('actor', actorId);
+    const highAlerts = actorAlerts.filter(a => a.severity === 'high');
+    const anomalyImpact =
+      actorAlerts.length * this.weights.anomaly_weight +
+      highAlerts.length * this.weights.high_severity_weight;
+    score -= anomalyImpact;
+
+    // 2. DLP component
+    const dlpEvents = this.auditLogger
+      .getEventsByType('DLP_SCANNED')
+      .filter(e => e.actor_id === actorId);
+    const dlpWithDetections = dlpEvents.filter(e => {
+      const detected = e.metadata?.detected as string[] | undefined;
+      return detected && detected.length > 0;
+    });
+    const dlpHighSeverity = dlpEvents.filter(e => e.metadata?.severity === 'high');
+    const dlpImpact =
+      dlpWithDetections.length * this.weights.dlp_weight +
+      dlpHighSeverity.length * this.weights.dlp_high_weight;
+    score -= dlpImpact;
+
+    // 3. Error rate component
+    const baseline = this.anomalyDetector.getBaseline('actor', actorId, 'error_rate');
+    const errorPct = baseline ? baseline.mean * 100 : 0;
+    const errorImpact = errorPct * this.weights.error_rate_weight;
+    score -= errorImpact;
+
+    // 4. Capability escalation component
+    const escalations = actorAlerts.filter(a => a.anomaly_type === 'capability_escalation');
+    const escalationImpact = escalations.length * this.weights.escalation_weight;
+    score -= escalationImpact;
+
+    // 5. Budget velocity component
+    const spending = this.budgetManager.getActorSpending(actorId);
+    // If daily spend is more than 2x the average per-task spend, flag it
+    let budgetVelocityRate = 0;
+    let budgetImpact = 0;
+    if (spending.task_count > 0 && spending.total_spend > 0) {
+      const avgPerTask = spending.total_spend / spending.task_count;
+      budgetVelocityRate = spending.daily_spend / avgPerTask;
+      if (budgetVelocityRate > 2) {
+        budgetImpact = this.weights.budget_velocity_weight;
+        score -= budgetImpact;
+      }
+    }
+
+    score = Math.max(0, Math.min(100, score));
+
+    const risk_level: TrustScoreResult['risk_level'] =
+      score >= 80 ? 'low' : score >= 50 ? 'medium' : score >= 30 ? 'high' : 'critical';
+
+    return {
+      actor_id: actorId,
+      score,
+      risk_level,
+      breakdown: {
+        anomalies: {
+          count: actorAlerts.length,
+          high_count: highAlerts.length,
+          impact: anomalyImpact,
+        },
+        dlp: {
+          detections: dlpWithDetections.length,
+          high_severity: dlpHighSeverity.length,
+          impact: dlpImpact,
+        },
+        error_rate: {
+          pct: errorPct,
+          impact: errorImpact,
+        },
+        escalations: {
+          count: escalations.length,
+          impact: escalationImpact,
+        },
+        budget_velocity: {
+          current_rate: budgetVelocityRate,
+          impact: budgetImpact,
+        },
+      },
+      calculated_at: new Date().toISOString(),
+    };
+  }
+
+  getLeaderboard(actorIds: string[]): TrustScoreResult[] {
+    return actorIds
+      .map(id => this.calculate(id))
+      .sort((a, b) => b.score - a.score);
+  }
+}

package/src/trust/index.ts

@@ -0,0 +1,7 @@
+export {
+  TrustScoreCalculator,
+  TrustScoreWeights,
+  TrustScoreBreakdown,
+  TrustScoreResult,
+  DEFAULT_WEIGHTS,
+} from './calculator';

package/src/types/budget.ts

@@ -0,0 +1,36 @@
+export interface TokenPricing {
+  input_per_token: number;
+  output_per_token: number;
+  /** Multiplier for cache creation tokens vs input price (default: 1.25) */
+  cache_creation_multiplier?: number;
+  /** Multiplier for cache read tokens vs input price (default: 0.1) */
+  cache_read_multiplier?: number;
+}
+
+export interface BudgetConfig {
+  task_budget_usd?: number;
+  user_daily_budget_usd?: number;
+  user_monthly_budget_usd?: number;
+  workspace_daily_budget_usd?: number;
+  workspace_monthly_budget_usd?: number;
+  max_steps_per_task?: number;
+  max_retries_per_call?: number;
+  max_wall_clock_ms?: number;
+  cost_table?: Record<string, number>;
+  token_pricing?: Record<string, TokenPricing>;
+}
+
+export interface BudgetState {
+  task_id: string;
+  workspace_id: string;
+  actor_id: string;
+  spent_usd: number;
+  steps: number;
+  started_at: string;
+}
+
+export interface CostEstimate {
+  tool_name: string;
+  capability: string;
+  estimated_cost_usd: number;
+}

package/src/types/config.ts

@@ -0,0 +1,278 @@
+import { BudgetConfig } from './budget';
+import { TracingConfig } from '../tracing';
+import { AnomalyConfig } from '../anomaly';
+import { OAuthConfig, FrontendConfig } from './user';
+import { StripeConfig } from './stripe-config';
+
+export interface GatewayConfig {
+  port: number;
+  host: string;
+  auth: AuthConfig;
+  policy: PolicyConfig;
+  dlp: DLPConfig;
+  budget: BudgetConfig;
+  audit: AuditConfig;
+  executor: ExecutorConfig;
+  approval: ApprovalConfig;
+  rate_limit?: RateLimitConfig;
+  tracing?: TracingConfig;
+  anomaly?: AnomalyConfig;
+  /** Rate limit for public endpoints (health, metrics). Default: 60 req/min */
+  public_rate_limit?: {
+    max_per_window: number;
+    window_ms: number;
+  };
+  /** Forward proxy configuration */
+  proxy?: ProxyConfig;
+  /** CORS allowed origins. Defaults to '*' in development, must be set in production. */
+  cors_origins?: string[];
+  /** OAuth configuration for SaaS login (Google/GitHub) */
+  oauth?: OAuthConfig;
+  /** Frontend SPA configuration */
+  frontend?: FrontendConfig;
+  /** Stripe billing configuration */
+  stripe?: StripeConfig;
+  /** MCP OAuth 2.0 configuration for Claude Code / MCP client auth */
+  mcp_oauth?: MCPOAuthConfig;
+}
+
+export interface MCPOAuthConfig {
+  enabled: boolean;
+  /** Base URL for OAuth endpoints (default: derived from host + port) */
+  base_url?: string;
+  /** Access token TTL in seconds (default: 3600 = 1 hour) */
+  access_token_ttl?: number;
+  /** Refresh token TTL in seconds (default: 2592000 = 30 days) */
+  refresh_token_ttl?: number;
+}
+
+export interface AuthConfig {
+  enabled: boolean;
+
+  // API Key auth (existing, enhanced)
+  api_keys: Record<string, ApiKeyConfig>;
+
+  // JWT/OIDC auth
+  jwt?: JWTAuthConfig;
+
+  // RBAC
+  rbac?: RBACConfig;
+
+  // Legacy field kept for backward compatibility
+  jwt_secret?: string;
+
+  /** Trusted proxy IPs/CIDRs. Only trust X-Forwarded-For from these sources. */
+  trusted_proxies?: string[];
+}
+
+export interface ApiKeyConfig {
+  workspace_id: string;
+  description?: string;
+  roles?: string[];              // Roles for RBAC
+  rate_limit_override?: number;  // Per-key rate limit override
+  expires_at?: string;           // ISO date, undefined = never expires
+  created_at?: string;           // ISO date
+  last_used_at?: string;         // ISO date, updated on use
+  revoked?: boolean;             // Soft-revoke without deleting
+}
+
+export interface JWTAuthConfig {
+  enabled: boolean;
+  // Static secret (for simple setups)
+  secret?: string;
+  // JWKS endpoint (for OIDC providers like Auth0, Okta, etc.)
+  jwks_uri?: string;
+  // JWT validation options
+  issuer?: string;               // Expected issuer
+  audience?: string;             // Expected audience
+  algorithms?: string[];         // Allowed algorithms (default: ['RS256', 'HS256'])
+  // Claim mappings
+  workspace_claim?: string;      // JWT claim for workspace_id (default: 'workspace_id')
+  roles_claim?: string;          // JWT claim for roles (default: 'roles')
+  actor_claim?: string;          // JWT claim for actor identity (default: 'sub')
+}
+
+export interface RBACConfig {
+  enabled: boolean;
+  roles: Record<string, RoleDefinition>;
+  default_role?: string;         // Role applied when no role is found
+}
+
+export interface RoleDefinition {
+  description?: string;
+  permissions: Permission[];
+}
+
+export type Permission =
+  | 'tool:execute'               // Can execute tool calls
+  | 'tool:execute:read'          // Can execute read-only tool calls
+  | 'tool:execute:write'         // Can execute write tool calls
+  | 'tool:execute:delete'        // Can execute delete tool calls
+  | 'tool:execute:admin'         // Can execute admin tool calls
+  | 'approval:manage'            // Can approve/deny pending approvals
+  | 'policy:read'                // Can view policies
+  | 'policy:write'               // Can validate/update policies
+  | 'trace:read'                 // Can view audit traces
+  | 'admin:full'                 // Full admin access (everything)
+  | string;                      // Custom permissions
+
+export interface PolicyConfig {
+  pack_path: string;
+  default_effect: 'ALLOW' | 'DENY';
+  hot_reload: boolean;
+  /** OPA policy engine configuration (optional, works alongside YAML engine) */
+  opa?: OPAConfig;
+}
+
+export interface OPAConfig {
+  enabled: boolean;
+  /** OPA server URL (e.g., 'http://localhost:8181') */
+  server_url?: string;
+  /** Policy path in OPA (e.g., 'v1/data/palaryn/policy') */
+  policy_path?: string;
+  /** Rego policy string (for inline/local evaluation without OPA server) */
+  rego_policy?: string;
+  /** Timeout for OPA requests in ms (default: 5000) */
+  timeout_ms?: number;
+  /** Fallback decision if OPA is unreachable (default: 'deny') */
+  fallback_decision?: 'allow' | 'deny' | 'transform' | 'require_approval';
+  /** Default Rego package name for inline policies (default: 'palaryn.policy') */
+  package_name?: string;
+}
+
+export interface DLPConfig {
+  enabled: boolean;
+  scan_args: boolean;
+  scan_output: boolean;
+  secrets_detection: boolean;
+  pii_detection: boolean;
+  prompt_injection_detection?: boolean;
+  /** Action when prompt injection is detected: 'log' (default), 'flag', or 'block' */
+  prompt_injection_action?: 'log' | 'flag' | 'block';
+  /** Minimum severity to trigger blocking (when action is 'block'). Default: 'high' */
+  prompt_injection_block_threshold?: 'medium' | 'high';
+  /** Response mode when injection is blocked: 'deny' (default), 'sanitize', or 'require_approval' */
+  prompt_injection_response?: 'deny' | 'sanitize' | 'require_approval';
+  default_redaction_method: 'mask' | 'hash' | 'drop' | 'tokenize';
+  trufflehog?: {
+    enabled: boolean;
+    binary_path?: string;
+    timeout_ms?: number;
+  };
+}
+
+export interface AuditConfig {
+  enabled: boolean;
+  log_dir: string;
+  console_output: boolean;
+  retention_days: number;
+}
+
+export interface FilesystemExecutorConfig {
+  enabled: boolean;
+  /** Root directory for sandboxed file operations */
+  base_dir: string;
+  /** Allowed file extensions (e.g., ['.txt', '.json']). Empty = all allowed. */
+  allowed_extensions?: string[];
+  /** Maximum file size in bytes (default: 10MB) */
+  max_file_size_bytes: number;
+}
+
+export interface SQLExecutorConfig {
+  enabled: boolean;
+  /** PostgreSQL connection string */
+  connection_string: string;
+  /** Query timeout in milliseconds (default: 30000) */
+  timeout_ms: number;
+  /** If true, only SELECT statements are allowed (default: true) */
+  read_only: boolean;
+  /** Maximum number of rows returned (default: 1000) */
+  max_rows: number;
+  /** Table names to block from all queries */
+  blocked_tables?: string[];
+}
+
+export interface ShellExecutorConfig {
+  enabled: boolean;
+  /** Allowed commands (empty = nothing allowed) */
+  allowed_commands: string[];
+  /** Blocked commands/patterns (checked even if allowed) */
+  blocked_commands?: string[];
+  /** Command timeout in milliseconds (default: 30000) */
+  timeout_ms: number;
+  /** Working directory for command execution */
+  cwd?: string;
+  /** Maximum output size in bytes (default: 1MB) */
+  max_output_bytes: number;
+}
+
+export interface WebSocketExecutorConfig {
+  enabled: boolean;
+  /** Allowed WebSocket URLs (glob patterns) */
+  allowed_urls: string[];
+  /** Connection timeout in milliseconds (default: 10000) */
+  connect_timeout_ms: number;
+  /** Maximum message size in bytes (default: 1MB) */
+  max_message_size_bytes: number;
+}
+
+export interface ProviderInterceptConfig {
+  enabled: boolean;
+  /** URL patterns for AI provider APIs to intercept (regex strings) */
+  provider_url_patterns?: string[];
+  /** Scan tool inputs in request bodies */
+  scan_inputs: boolean;
+  /** Scan tool outputs in response bodies */
+  scan_outputs: boolean;
+}
+
+export interface ExecutorConfig {
+  http: {
+    timeout_ms: number;
+    max_retries: number;
+    backoff_base_ms: number;
+  };
+  cache: {
+    enabled: boolean;
+    ttl_ms: number;
+  };
+  filesystem?: FilesystemExecutorConfig;
+  sql?: SQLExecutorConfig;
+  shell?: ShellExecutorConfig;
+  websocket?: WebSocketExecutorConfig;
+  provider_intercept?: ProviderInterceptConfig;
+}
+
+export interface ApprovalConfig {
+  enabled: boolean;
+  token_secret: string;
+  default_ttl_seconds: number;
+  webhook_url?: string;
+  webhook_headers?: Record<string, string>;
+}
+
+export interface RateLimitConfig {
+  enabled: boolean;
+  /** Max requests per actor per window */
+  actor_max_per_window: number;
+  /** Max requests per workspace per window */
+  workspace_max_per_window: number;
+  /** Window duration in milliseconds */
+  window_ms: number;
+}
+
+export interface ProxyConfig {
+  enabled: boolean;
+  /** Port for the forward proxy server (default: 3128) */
+  port: number;
+  /** Domains to skip proxy pipeline for (e.g. palaryn's own domain) */
+  passthrough_domains?: string[];
+  /** Default workspace ID for sidecar mode (no per-request auth needed) */
+  default_workspace_id?: string;
+  /** Default actor ID for sidecar mode */
+  default_actor_id?: string;
+  /** Require Proxy-Authorization for every request (default: true unless sidecar defaults set) */
+  require_auth?: boolean;
+  /** Enable SSRF protection to block requests to private IPs (default: true) */
+  ssrf_protection?: boolean;
+}

package/src/types/events.ts

@@ -0,0 +1,41 @@
+export type EventType =
+  | 'TOOL_CALL_RECEIVED'
+  | 'POLICY_DECIDED'
+  | 'DLP_SCANNED'
+  | 'BUDGET_CHECKED'
+  | 'TOOL_EXECUTED'
+  | 'TOOL_RESULT_RETURNED'
+  | 'APPROVAL_REQUESTED'
+  | 'APPROVAL_APPROVED'
+  | 'APPROVAL_DENIED'
+  | 'APPROVAL_EXPIRED'
+  | 'INCIDENT_RAISED'
+  | 'USAGE_REPORTED'
+  | 'POLICY_UPDATED'
+  | 'POLICY_RESET';
+
+export type IncidentSeverity = 'low' | 'medium' | 'high' | 'critical';
+
+export interface AuditEvent {
+  event_id: string;
+  event_type: EventType;
+  timestamp: string;
+  tool_call_id: string;
+  session_id?: string;
+  task_id: string;
+  workspace_id: string;
+  actor_id: string;
+  tool_name: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface IncidentEvent extends AuditEvent {
+  event_type: 'INCIDENT_RAISED';
+  metadata: {
+    severity: IncidentSeverity;
+    incident_type: string;
+    description: string;
+    recommended_action: string;
+    [key: string]: unknown;
+  };
+}

package/src/types/express.d.ts

@@ -0,0 +1,14 @@
+import { User, Session } from './user';
+
+declare module 'express-serve-static-core' {
+  interface Request {
+    /** Workspace ID set by auth middleware (backward compat) */
+    workspace_id?: string;
+    /** API key description set by auth middleware */
+    api_key_description?: string;
+    /** Authenticated user (set by session middleware) */
+    sessionUser?: User;
+    /** Session data (set by session middleware) */
+    sessionData?: Session;
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export * from './tool-call';
+export * from './tool-result';
+export * from './policy';
+export * from './events';
+export * from './budget';
+export * from './config';
+export * from './user';