opalserve 0.1.0

package/src/core/auth.ts

@@ -0,0 +1,109 @@
+import jwt from 'jsonwebtoken';
+import type { Request, Response, NextFunction } from 'express';
+
+export interface AuthContext {
+  agentId: string;
+  permissions: string[];
+  context: Record<string, unknown>;
+}
+
+export interface JWTPayload {
+  agentId: string;
+  permissions: string[];
+  context: Record<string, unknown>;
+  iat: number;
+  exp: number;
+}
+
+export class AuthService {
+  private secret: string;
+  private apiKey?: string;
+
+  constructor(secret: string, apiKey?: string) {
+    this.secret = secret;
+    this.apiKey = apiKey;
+  }
+
+  generateToken(context: AuthContext): string {
+    return jwt.sign(
+      {
+        agentId: context.agentId,
+        permissions: context.permissions,
+        context: context.context,
+      },
+      this.secret,
+      { expiresIn: '24h' }
+    );
+  }
+
+  verifyToken(token: string): AuthContext | null {
+    try {
+      const payload = jwt.verify(token, this.secret) as JWTPayload;
+      return {
+        agentId: payload.agentId,
+        permissions: payload.permissions,
+        context: payload.context,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  verifyApiKey(key: string): boolean {
+    if (!this.apiKey) return false;
+    return key === this.apiKey;
+  }
+
+  extractAuth(req: Request): AuthContext | null {
+    const authHeader = req.headers.authorization;
+
+    if (authHeader?.startsWith('Bearer ')) {
+      const token = authHeader.slice(7);
+      return this.verifyToken(token);
+    }
+
+    const apiKey = req.headers['x-api-key'] as string;
+    if (apiKey && this.verifyApiKey(apiKey)) {
+      return {
+        agentId: 'api-key-user',
+        permissions: ['read', 'discover'],
+        context: {},
+      };
+    }
+
+    return null;
+  }
+
+  middleware() {
+    return (req: Request, res: Response, next: NextFunction) => {
+      const auth = this.extractAuth(req);
+      if (!auth) {
+        res.status(401).json({ error: 'Unauthorized' });
+        return;
+      }
+      (req as Request & { auth: AuthContext }).auth = auth;
+      next();
+    };
+  }
+
+  optionalAuth() {
+    return (req: Request, _res: Response, next: NextFunction) => {
+      const auth = this.extractAuth(req);
+      if (auth) {
+        (req as Request & { auth: AuthContext }).auth = auth;
+      }
+      next();
+    };
+  }
+
+  checkPermission(permission: string) {
+    return (req: Request, res: Response, next: NextFunction) => {
+      const auth = (req as Request & { auth: AuthContext }).auth;
+      if (!auth || !auth.permissions.includes(permission)) {
+        res.status(403).json({ error: 'Forbidden', required: permission });
+        return;
+      }
+      next();
+    };
+  }
+}

package/src/core/registry.ts

@@ -0,0 +1,301 @@
+import type { Tool, Server, DiscoveryQuery, DiscoveryResult, MCPServer } from '../types/index.js';
+import { TokenCounter } from './tokenizer.js';
+
+interface IndexedTool {
+  tool: Tool;
+  searchableText: string;
+  tokenCount: number;
+}
+
+export class ToolRegistry {
+  private tools: Map<string, IndexedTool> = new Map();
+  private servers: Map<string, Server> = new Map();
+  private serverInstances: Map<string, MCPServer> = new Map();
+  private tokenCounter: TokenCounter;
+
+  constructor(contextBudget: number = 128000) {
+    this.tokenCounter = new TokenCounter(contextBudget);
+  }
+
+  registerTool(tool: Tool): void {
+    const searchableText = this.buildSearchableText(tool);
+    const indexedTool: IndexedTool = {
+      tool,
+      searchableText,
+      tokenCount: this.tokenCounter.count(searchableText),
+    };
+    this.tools.set(tool.id, indexedTool);
+  }
+
+  registerServer(server: Server): void {
+    this.servers.set(server.id, server);
+  }
+
+  registerServerInstance(instance: MCPServer): void {
+    this.serverInstances.set(instance.id, instance);
+  }
+
+  removeTool(toolId: string): boolean {
+    return this.tools.delete(toolId);
+  }
+
+  removeServer(serverId: string): boolean {
+    this.servers.delete(serverId);
+    this.serverInstances.delete(serverId);
+    for (const [toolId, indexed] of this.tools) {
+      if (indexed.tool.serverId === serverId) {
+        this.tools.delete(toolId);
+      }
+    }
+    return true;
+  }
+
+  getTool(toolId: string): Tool | undefined {
+    return this.tools.get(toolId)?.tool;
+  }
+
+  getServer(serverId: string): Server | undefined {
+    return this.servers.get(serverId);
+  }
+
+  getAllTools(): Tool[] {
+    return Array.from(this.tools.values()).map(i => i.tool);
+  }
+
+  getAllServers(): Server[] {
+    return Array.from(this.servers.values());
+  }
+
+  getToolsByServer(serverId: string): Tool[] {
+    return Array.from(this.tools.values())
+      .filter(i => i.tool.serverId === serverId)
+      .map(i => i.tool);
+  }
+
+  async discover(query: DiscoveryQuery): Promise<DiscoveryResult> {
+    const tools = this.scoreAndFilterTools(query);
+    const servers = this.getServersForTools(tools.map(t => t.tool.serverId));
+    const contextUsed = this.calculateContextUsed(tools);
+    const queryInterpretation = this.interpretQuery(query);
+
+    return {
+      tools: tools.map(({ tool, relevanceScore, matchReasons, tokenEstimate }) => ({
+        tool,
+        relevanceScore,
+        matchReasons,
+        tokenEstimate,
+      })),
+      servers,
+      totalMatches: tools.length,
+      contextUsed,
+      contextBudget: query.contextBudget,
+      suggestions: this.generateSuggestions(query),
+      queryInterpretation,
+    };
+  }
+
+  private scoreAndFilterTools(query: DiscoveryQuery): Array<{
+    tool: Tool;
+    relevanceScore: number;
+    matchReasons: string[];
+    tokenEstimate: number;
+  }> {
+    const scored: Array<{
+      tool: Tool;
+      relevanceScore: number;
+      matchReasons: string[];
+      tokenEstimate: number;
+    }> = [];
+
+    let contextUsed = 0;
+    const headerTokens = 200;
+
+    for (const indexed of this.tools.values()) {
+      const { tool, tokenCount } = indexed;
+      if (contextUsed + tokenCount + headerTokens > query.contextBudget && scored.length > 0) {
+        break;
+      }
+
+      const { score, reasons } = this.calculateRelevance(tool, query);
+
+      if (score > 0) {
+        if (query.capabilities?.length) {
+          const hasCapability = query.capabilities.some(cap =>
+            tool.capabilities.includes(cap)
+          );
+          if (!hasCapability) continue;
+        }
+
+        if (query.tags?.length) {
+          const hasTag = query.tags.some(tag => tool.tags.includes(tag));
+          if (!hasTag) continue;
+        }
+
+        scored.push({
+          tool,
+          relevanceScore: score,
+          matchReasons: reasons,
+          tokenEstimate: tokenCount,
+        });
+        contextUsed += tokenCount;
+      }
+    }
+
+    scored.sort((a, b) => b.relevanceScore - a.relevanceScore);
+
+    const limit = Math.min(query.limit, this.findContextFitLimit(scored, query.contextBudget));
+    return scored.slice(query.offset, query.offset + limit);
+  }
+
+  private calculateRelevance(tool: Tool, query: DiscoveryQuery): {
+    score: number;
+    reasons: string[];
+  } {
+    let score = 0;
+    const reasons: string[] = [];
+
+    if (query.query) {
+      const q = query.query.toLowerCase();
+      const words = q.split(/\s+/);
+
+      for (const word of words) {
+        if (tool.name.toLowerCase().includes(word)) {
+          score += 0.4;
+          reasons.push(`Name matches "${word}"`);
+        }
+        if (tool.description.toLowerCase().includes(word)) {
+          score += 0.3;
+          reasons.push(`Description matches "${word}"`);
+        }
+        for (const tag of tool.tags) {
+          if (tag.toLowerCase().includes(word)) {
+            score += 0.2;
+            reasons.push(`Tag "${tag}" matches "${word}"`);
+          }
+        }
+        for (const cap of tool.capabilities) {
+          if (cap.toLowerCase().includes(word)) {
+            score += 0.25;
+            reasons.push(`Capability "${cap}" matches "${word}"`);
+          }
+        }
+      }
+
+      const allText = `${tool.name} ${tool.description} ${tool.tags.join(' ')} ${tool.capabilities.join(' ')}`.toLowerCase();
+      const matchCount = words.filter(w => allText.includes(w)).length;
+      if (matchCount === words.length) {
+        score += 0.3;
+        reasons.push('All query terms matched');
+      }
+    }
+
+    return { score: Math.min(score, 1), reasons };
+  }
+
+  private getServersForTools(serverIds: string[]): Server[] {
+    const uniqueIds = [...new Set(serverIds)];
+    return uniqueIds
+      .map(id => this.servers.get(id))
+      .filter((s): s is Server => s !== undefined);
+  }
+
+  private calculateContextUsed(tools: Array<{ tokenEstimate: number }>): number {
+    return tools.reduce((sum, t) => sum + t.tokenEstimate, 0) + 200;
+  }
+
+  private findContextFitLimit(tools: Array<{ tokenEstimate: number }>, budget: number): number {
+    let used = 200;
+    for (let i = 0; i < tools.length; i++) {
+      if (used + tools[i].tokenEstimate > budget) {
+        return i;
+      }
+      used += tools[i].tokenEstimate;
+    }
+    return tools.length;
+  }
+
+  private interpretQuery(query: DiscoveryQuery): string {
+    if (!query.query) {
+      return 'Returning all available tools sorted by relevance';
+    }
+
+    const q = query.query.toLowerCase();
+    const interpretations: string[] = [];
+
+    if (q.includes('what can i do') || q.includes('available') || q.includes('list')) {
+      interpretations.push('Listing available actions');
+    }
+    if (q.includes('github') || q.includes('repo') || q.includes('pr')) {
+      interpretations.push('Looking for GitHub-related tools');
+    }
+    if (q.includes('slack') || q.includes('message') || q.includes('channel')) {
+      interpretations.push('Looking for Slack/messaging tools');
+    }
+    if (q.includes('database') || q.includes('query') || q.includes('sql')) {
+      interpretations.push('Looking for database tools');
+    }
+    if (q.includes('file') || q.includes('drive') || q.includes('document')) {
+      interpretations.push('Looking for file/document tools');
+    }
+
+    if (interpretations.length === 0) {
+      return `Searching for tools matching: "${query.query}"`;
+    }
+
+    return interpretations.join(', ');
+  }
+
+  private generateSuggestions(query: DiscoveryQuery): string[] {
+    const suggestions: string[] = [];
+
+    if (this.tools.size > 50 && query.limit && query.limit < 10) {
+      suggestions.push('Try increasing the limit to see more tools');
+    }
+
+    if (!query.query && this.tools.size > 50) {
+      suggestions.push('Use a query to filter tools by capability or name');
+    }
+
+    const hasGitHub = Array.from(this.tools.values()).some(
+      i => i.tool.serverName.toLowerCase().includes('github')
+    );
+    if (!hasGitHub) {
+      suggestions.push('Configure GitHub connector for repository management');
+    }
+
+    return suggestions;
+  }
+
+  private buildSearchableText(tool: Tool): string {
+    return [
+      tool.name,
+      tool.description,
+      ...tool.tags,
+      ...tool.capabilities,
+      tool.serverName,
+    ].join(' ');
+  }
+
+  async healthCheck(serverId: string): Promise<{ healthy: boolean; latencyMs?: number }> {
+    const instance = this.serverInstances.get(serverId);
+    if (!instance) {
+      return { healthy: false };
+    }
+    return instance.healthCheck();
+  }
+
+  async refreshServer(serverId: string): Promise<void> {
+    const instance = this.serverInstances.get(serverId);
+    const server = this.servers.get(serverId);
+    if (!instance || !server) return;
+
+    try {
+      await instance.disconnect();
+      await instance.connect();
+      server.status = 'active';
+      server.lastSeen = new Date().toISOString();
+    } catch {
+      server.status = 'error';
+    }
+  }
+}

package/src/core/tokenizer.ts

@@ -0,0 +1,40 @@
+export class TokenCounter {
+  private contextBudget: number;
+
+  constructor(contextBudget: number = 128000) {
+    this.contextBudget = contextBudget;
+  }
+
+  count(text: string): number {
+    return Math.ceil(text.length / 4);
+  }
+
+  estimateToolTokens(tool: {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    tags?: string[];
+    capabilities?: string[];
+  }): number {
+    const parts = [
+      tool.name,
+      tool.description,
+      JSON.stringify(tool.inputSchema || {}),
+      (tool.tags || []).join(' '),
+      (tool.capabilities || []).join(' '),
+    ];
+    return this.count(parts.join(' ')) + 20;
+  }
+
+  canFit(tokens: number, currentUsage: number = 0): boolean {
+    return (currentUsage + tokens) <= this.contextBudget;
+  }
+
+  remaining(currentUsage: number = 0): number {
+    return Math.max(0, this.contextBudget - currentUsage);
+  }
+
+  setBudget(budget: number): void {
+    this.contextBudget = budget;
+  }
+}

package/src/governance/audit.ts

@@ -0,0 +1,182 @@
+import type { AuditEvent, AuditEventType, ComplianceReport } from './types.js';
+
+export class AuditLogger {
+  private events: AuditEvent[] = [];
+  private maxEvents: number;
+
+  constructor(maxEvents: number = 10000) {
+    this.maxEvents = maxEvents;
+  }
+
+  log(event: Omit<AuditEvent, 'id' | 'timestamp'>): AuditEvent {
+    const fullEvent: AuditEvent = {
+      id: `audit-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+      timestamp: new Date().toISOString(),
+      ...event,
+      metadata: event.metadata || {},
+      context: event.context || {},
+    };
+
+    this.events.push(fullEvent);
+
+    if (this.events.length > this.maxEvents) {
+      this.events = this.events.slice(-this.maxEvents);
+    }
+
+    return fullEvent;
+  }
+
+  logToolAccess(agentId: string, agentName: string, toolId: string, result: 'success' | 'denied' | 'error', requestId: string, reason?: string): void {
+    this.log({
+      type: result === 'denied' ? 'tool.denied' : result === 'error' ? 'tool.error' : 'tool.accessed',
+      agentId,
+      agentName,
+      requestId,
+      resourceType: 'tool',
+      resourceId: toolId,
+      action: 'access',
+      result,
+      reason,
+      metadata: {},
+      context: {},
+    });
+  }
+
+  logAuthentication(agentId: string, agentName: string, success: boolean, requestId: string, ipAddress?: string): void {
+    this.log({
+      type: success ? 'identity.authenticated' : 'identity.auth_failed',
+      agentId: success ? agentId : undefined,
+      agentName: success ? agentName : undefined,
+      requestId,
+      ipAddress,
+      action: 'authenticate',
+      result: success ? 'success' : 'denied',
+      metadata: { ipAddress },
+      context: {},
+    });
+  }
+
+  logToolExecution(agentId: string, agentName: string, toolId: string, success: boolean, requestId: string, durationMs?: number, error?: string): void {
+    this.log({
+      type: success ? 'tool.executed' : 'tool.error',
+      agentId,
+      agentName,
+      requestId,
+      resourceType: 'tool',
+      resourceId: toolId,
+      action: 'execute',
+      result: success ? 'success' : 'error',
+      reason: error,
+      metadata: { durationMs },
+      context: {},
+    });
+  }
+
+  logPermissionCheck(agentId: string, permission: string, allowed: boolean, requestId: string, reason?: string): void {
+    this.log({
+      type: allowed ? 'permission.checked' : 'permission.denied',
+      agentId,
+      requestId,
+      action: `check:${permission}`,
+      result: allowed ? 'success' : 'denied',
+      reason,
+      metadata: {},
+      context: {},
+    });
+  }
+
+  getEvents(options?: {
+    type?: AuditEventType;
+    agentId?: string;
+    resourceType?: string;
+    resourceId?: string;
+    result?: 'success' | 'denied' | 'error';
+    since?: string;
+    until?: string;
+    limit?: number;
+    offset?: number;
+  }): AuditEvent[] {
+    let filtered = [...this.events];
+
+    if (options?.type) {
+      filtered = filtered.filter(e => e.type === options.type);
+    }
+    if (options?.agentId) {
+      filtered = filtered.filter(e => e.agentId === options.agentId);
+    }
+    if (options?.resourceType) {
+      filtered = filtered.filter(e => e.resourceType === options.resourceType);
+    }
+    if (options?.resourceId) {
+      filtered = filtered.filter(e => e.resourceId === options.resourceId);
+    }
+    if (options?.result) {
+      filtered = filtered.filter(e => e.result === options.result);
+    }
+    if (options?.since) {
+      filtered = filtered.filter(e => e.timestamp >= options.since!);
+    }
+    if (options?.until) {
+      filtered = filtered.filter(e => e.timestamp <= options.until!);
+    }
+
+    filtered.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+    const offset = options?.offset || 0;
+    const limit = options?.limit || 100;
+    return filtered.slice(offset, offset + limit);
+  }
+
+  generateComplianceReport(periodStart: string, periodEnd: string): ComplianceReport {
+    const events = this.getEvents({ since: periodStart, until: periodEnd });
+
+    const byType: Record<string, number> = {};
+    const byAgent: Record<string, number> = {};
+
+    for (const event of events) {
+      byType[event.type] = (byType[event.type] || 0) + 1;
+      if (event.agentId) {
+        byAgent[event.agentId] = (byAgent[event.agentId] || 0) + 1;
+      }
+    }
+
+    const deniedAccess = events.filter(e => e.result === 'denied').length;
+    const rateLimitExceeded = events.filter(e => e.type === 'rate_limit.exceeded').length;
+    const policyViolations = events.filter(e => e.type === 'permission.denied' || e.type === 'tool.denied').length;
+
+    const recommendations: string[] = [];
+    if (deniedAccess > events.length * 0.1) {
+      recommendations.push('High rate of denied access - review permission configurations');
+    }
+    if (rateLimitExceeded > 100) {
+      recommendations.push('Frequent rate limit violations - consider increasing limits or optimizing usage');
+    }
+    if (Object.keys(byAgent).length < 5) {
+      recommendations.push('Limited user diversity - ensure proper access distribution');
+    }
+
+    return {
+      generatedAt: new Date().toISOString(),
+      period: { start: periodStart, end: periodEnd },
+      totalEvents: events.length,
+      byType,
+      byAgent,
+      deniedAccess,
+      rateLimitExceeded,
+      policyViolations,
+      recommendations,
+    };
+  }
+
+  clear(): void {
+    this.events = [];
+  }
+
+  export(): AuditEvent[] {
+    return [...this.events];
+  }
+
+  import(events: AuditEvent[]): void {
+    this.events = [...this.events, ...events].slice(-this.maxEvents);
+  }
+}

package/src/governance/index.ts

@@ -0,0 +1,4 @@
+export { AuditLogger } from './audit.js';
+export { PolicyEngine } from './policy.js';
+export { RateLimiter, type RateLimitConfig } from './rate-limiter.js';
+export * from './types.js';